Implementation, Transaction Processing: Capturing Transactions for Settlement

The following operations are used for the capture and settlement of transactions for both SOAP and REST implementations:

Capture Operations  
Capture(BCP, SVA) CaptureSelective (BCP only)
CaptureAll (BCP, ECK) CaptureSelectiveAsync (BCP only)
CaptureAllAsync (BCP only)   

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

 


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

SOAP

Operation

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

Parameters

Parameter Data Type Description
sessionToken String The short-lived token used to authenticate to CWS.
differenceData Capture The capture details for a single transaction.
Note: You must send in BankcardCapture 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 Capture response data.
Note: For Bankcard (BCP) transactions, the response object is BankcardCaptureResponse.
For Electronic Checking (ECK) transactions, the response object is ElectronicCheckingCaptureResponse.
For Stored Value Account (SVA) transactions, the response object is StoredValueCaptureResponse.

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 Samples

<?php

        require_once(dirname(__FILE__) . '/AuthOnly.php');
   		
		/*
		*BankcardCapture Class needed for Capture
		*\
		*/
		class BankcardCapture {
		   public $ChargeType;
		   public $TransactionId;
		   public $Addendum;
		}
		
		$capture = new BankcardCapture();
		$capture->TransactionId = $response[2];
		$capture->ChargeType = 'NotSet';
		
		$captureParam = '<ns2:TransactionId xmlns:ns2="http://schemas.ipcommerce.com/CWS/v2.0/Transactions">'.$capture->TransactionId.'</ns2:TransactionId>
							<ns1:ChargeType>'.$capture->ChargeType.'</ns1:ChargeType>';
		
		$transactionCapture = '<?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>
								<Capture xmlns="http://schemas.ipcommerce.com/CWS/v2.0/TransactionProcessing">
								  <sessionToken>'.$sessionTokenString.'</sessionToken>
								  <differenceData xsi:type="ns1:BankcardCapture" xmlns:ns1="http://schemas.ipcommerce.com/CWS/v2.0/Transactions/Bankcard">'
									.$captureParam.
							     '</differenceData>'
								  .'<applicationProfileId>'.$applicationIdString.'</applicationProfileId>'
								  .'<workflowId>'.$serviceId.'</workflowId>'
								.'</Capture>
							   </SOAP-ENV:Body>
							</SOAP-ENV:Envelope>';
		
		
	    $xmlRequest = $transactionCapture;
		$call = 'Capture';
		
		$response2 = curl_call($xmlRequest, $sessionTokenString, $call);
						
		if($response[0] != '')
		{
			echo nl2br("<h1>Capture Transaction Results</h1> \r\n 
				<h3>StatusMessage: " . $response2[0] . "</h3> 
				<h3>StatusCode: "    . $response2[1] . "</h3> 
				<h3>TransactionId: " . $response2[2] . "</h3> \r\n\r\n
				<h1>Captured!</h1>");
	    } else {
     		echo nl2br("<h1>Something Went Wrong</h1>");
	      	}
?>

C# Code Samples

public Response Capture(string sessionToken, Capture capture, string applicationProfileId, string workflowId)
{
	using (var client = new CwsTransactionProcessingClient(ConfigurationManager.AppSettings["Bindings.TxnSoap"]))
	{
		try
		{
			return client.Capture(sessionToken, capture, 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 captured.

Message Body Type

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

Return Type

Data Type Description
Response Capture response data.
Note: For Bankcard (BCP) transactions, the response object is BankcardCaptureResponse.
For Electronic Checking (ECK) transactions, the response object is ElectronicCheckingCaptureResponse.
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 Samples

/* $transactionID is the known transaction ID of a previous transaction
 * $amount is the amount of money to charge, leave it empty to charge existing amount
 * $tip_amount is the amount of tip money to charge, leave it empty to charge existing amount*/
 
public function capture($transactionID, $creds = null, $amount = null, $tip_amount = null)
{
	if (! $this->signOn ())
		return false;
 
	$CapType = '"$type":"Capture,http://schemas.nabcommerce.com/CWS/v2.0/Transactions/Rest",';
	$DiffType = '"$type":"BankcardCapture,http://schemas.nabcommerce.com/CWS/v2.0/Transactions/Bankcard",';
 
	$DifferenceData = new BankcardCapture ();
	$DifferenceData->TransactionId = $transactionID;
	$DifferenceData->Amount = $amount ? $amount:'0.00';
	$DifferenceData->TipAmount = $tip_amount ? $tip_amount:'0.00';
	$DifferenceData->ChargeType = 'NotSet'; // Conditional - If Industry is Retail, this value MUST be set.
	$DifferenceData->ShipDate = date('Y-m-d\TH:i:s.u\Z');
	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_Capture ();
	$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"', '{'.$CapType.'"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 Samples

public Response Capture(string sessionToken, Capture capture, string applicationProfileId, string workflowId)
{
	var isJson = string.Equals(_msgFormat, MessageFormat.JSON.ToString());
	var requestString = RestBaseUri + "/" + workflowId + "/" + capture.TransactionId;
	var restCapture = new schemas.nabcommerce.com.CWS.v2._0.Transactions.Rest.Capture();
	restCapture.ApplicationProfileId = applicationProfileId;
 
	if(capture.GetType() == typeof(BankcardCapture))
		restCapture.DifferenceData = Utilities.SwapObjectsNamespace(capture);
	else
		restCapture.DifferenceData = Utilities.SwapObjectsNamespace(capture);
 

	var request = RestHelper.CreateRestRequest(restCapture, 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("BankcardCaptureResponsePro"))
			return RestHelper.GetCWSObjectFromXml(strResponse);
		if (strResponse.Contains("ElectronicCheckingCaptureResponse"))
			return RestHelper.GetCWSObjectFromXml(strResponse);
		if (strResponse.Contains("StoredValueCaptureResponse"))
			return RestHelper.GetCWSObjectFromXml(strResponse);
	}
	catch (Exception ex)
	{
		RestFaultHandler.HandleFaultException(ex, isJson);
	}
}

 


 

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

SOAP

Operation

List CaptureAll(string sessionToken, List differenceData, List batchIds, string applicationProfileId, MerchantProfile merchantProfile, string merchantProfileId, string workflowId);

Parameters

Parameter Data Type Description
sessionToken String The short-lived token used to authenticate to CWS.
differenceData List<Capture> A list of one or more transactions to capture.
Note: You must send in BankcardCapture for Bankcard transactions.
batchIds List A list of one or more batch Ids to capture.
applicationProfileId String A token representing the PTLS Socket ID unique to each Service Key and configuration data combination. Returned by the SaveApplicationData operation.
merchantProfile MerchantProfile Conditional. The specific Merchant Profile to include in the transaction request. Required only if supporting Unmanaged Merchant Profiles (UMP).
merchantProfileId String The specific Merchant Profile Identifier to use.
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
List<Response> A collection of capture response data.
Note: For Bankcard (BCP) transactions, the response object is BankcardCaptureResponse.
For Electronic Checking (ECK) transactions, the response object is ElectronicCheckingCaptureResponse.
For Stored Value Account (SVA) transactions, the response object is StoredValueCaptureResponse.

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 Samples

/* $differenceData is an object that contains any data to adjust at the time of settlement */
 
public function captureAll($differenceData, $creds = null)
{
	if (! $this->signOn ())
		return false;
 
	if ($this->svc instanceof BankcardService)
	{
		$diffDataArray = array ();
		$caDiffData = new CaptureDifferenceData ();
 
		if ($differenceData != null)
		{
			$i = 0;
			if (is_array ( $differenceData ))
			{

				foreach ( $diffData as $differenceData )
				{
					$caDiffData->TransactionId = $diffData->transactionID;
					$caDiffData->Amount = $diffData->amount;
					$caDiffData->TipAmount = $diffData->tip_amount;
					$caDiffData->ShipDate = $diffData->shipDate;
					$diffDataArray [] = $caDiffData;
				}
			}
			else
			{
				$caDiffData->TransactionId = $diffData->transactionID;
				$caDiffData->Amount = $diffData->amount;
				$caDiffData->TipAmount = $diffData->tip_amount;
				$caDiffData->ShipDate = $diffData->shipDate;
				$diffDataArray [] = $caDiffData;
			}
			if ($creds != null)
			{
				$diffDataArray [0]->Addendum = new Addendum ();
				$diffDataArray [0]->Addendum->Unmanaged = new Unmanaged ();
				$diffDataArray [0]->Addendum->Unmanaged->Any = new Any ();
				$diffDataArray [0]->Addendum->Unmanaged->Any->string = $creds;
			}
		}
	}
 
	if ($creds != null)
	{
		$diffDataArray = array ();
		$caDiffData = new CaptureDifferenceData ();
		$caDiffData->TransactionId = '-1';
		$diffDataArray [] = $caDiffData;
		$diffDataArray [0]->Addendum = new Addendum ();
		$diffDataArray [0]->Addendum->Unmanaged = new Unmanaged ();
		$diffDataArray [0]->Addendum->Unmanaged->Any = new Any ();
		$diffDataArray [0]->Addendum->Unmanaged->Any->string = $creds;
	}
 
	// Build Capture
	$trans = new CaptureAll ();
	$trans->sessionToken = $this->session_token;
	$trans->differenceData = $diffDataArray;
	$trans->merchantProfileId = $this->merchantProfileID;
	$trans->workflowId = $this->workflowId;
	$trans->applicationProfileId = $this->appProfileID;
 
	try
	{
		$capAllResponse = $this->bankCard->CaptureAll ( $trans )->CaptureAllResult;
		//echo ('
'.$this->bankCard->__getLastRequestHeaders()); //echo ('
'.$this->bankCard->__getLastRequest()); //echo ('
'.$this->bankCard->__getLastResponseHeaders()); //echo ('
\n'.$this->bankCard->__getLastResponse().'\n'); return $capAllResponse; } catch ( SoapFault $e ) { /*echo "
REQUEST:\n" . $this->bankCard->__getLastRequest() . "\n
";*/ //process_soap_error ( $e ); echo 'SERVER ERROR: Error trying to Capture.
'; echo ('
'.$this->bankCard->__getLastRequest()); $xmlFault = $this->bankCard->__getLastResponse (); $errors = handleTxnFault ( $e, $xmlFault ); echo $errors; exit (); } }

C# Code Samples

public List CaptureAll(string sessionToken, List captures, string applicationProfileId, string merchantProfileId, string workflowId, List batchIds = null)
{
	Type type = typeof(T);
 
	if (_msgFormat == MessageFormat.SOAP.ToString())
	{
		var bankcardCaptures = new List();
		var regularCaptures = new List();
		if (type == typeof(BankcardCapture))
		{
			foreach (var capture in captures)
			{
				bankcardCaptures.Add(capture as BankcardCapture);
			}
		}
		else
		{
			foreach (var capture in captures)
			{
				regularCaptures.Add(capture as Capture);
			}
		}
	using (var client = new CwsTransactionProcessingClient(ConfigurationManager.AppSettings["Bindings.TxnSoap"]))
	{
		try
		{
			if(bankcardCaptures.Count > 0 && batchIds != null)
				return client.CaptureAll(sessionToken, bankcardCaptures.ToArray(), batchIds.ToArray(), applicationProfileId, merchantProfileId, workflowId).ToList();
			if(bankcardCaptures.Count > 0)
				return client.CaptureAll(sessionToken, bankcardCaptures.ToArray(), null, applicationProfileId, merchantProfileId, workflowId).ToList();
			if(batchIds != null)
				return client.CaptureAll(sessionToken, regularCaptures.ToArray(), batchIds.ToArray(), applicationProfileId, merchantProfileId, workflowId).ToList();
			return client.CaptureAll(sessionToken, regularCaptures.ToArray(), null, applicationProfileId, merchantProfileId, workflowId).ToList();
		}
		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}
UMP URL https://api.cert.nabcommerce.com/REST/2.0.18UMP/Txn/{workflowId}
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.

Message Body Type

Data Type Description
Rest.CaptureAll The message body containing transaction data.
Rest.CaptureAllWithProfile The message body containing transaction data and complete MerchantProfile required by UMP implementations.

Return Type

Data Type Description
List<Response> A collection of capture response data.
Note: For Bankcard (BCP) transactions, the response object is BankcardCaptureResponse.
For Electronic Checking (ECK) transactions, the response object is ElectronicCheckingCaptureResponse.
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 Samples

/* $differenceData is an object that contains any data to adjust at the time of settlement */
 
public function captureAll($differenceData, $creds = null)
{
	return false; // INCOMPLETE
}

C# Code Samples

public List CaptureAll(string sessionToken, List captures, string applicationProfileId, string merchantProfileId, string workflowId, List batchIds = null)
{
	var isJson = string.Equals(_msgFormat, MessageFormat.JSON.ToString());
	var requestString = RestBaseUri + "/" + workflowId;
	var restCaptureAll = new schemas.nabcommerce.com.CWS.v2._0.Transactions.Rest.CaptureAll();
	restCaptureAll.ApplicationProfileId = applicationProfileId;
	restCaptureAll.MerchantProfileId = merchantProfileId;
	// For Capture All in REST DifferenceData maybe set to null as well as batchId's so that all transactions will be batched together. 
	// If anything changed on a transaction between authorization and capture, the difference data needs to reflect this.
	restCaptureAll.DifferenceData = null;
	restCaptureAll.BatchIds = batchIds;
 
	var request = RestHelper.CreateRestRequest(restCaptureAll, requestString, HttpMethod.PUT, sessionToken, isJson);
	try
	{
		// The response is an array of specific capture response. First step is to get the CWS Object from the list. 
		// With JSON the conversion needs the fully typed namespace. 
		// After that it is coverted to the shorter namespace defined by the service reference. 
		// The last step converts this list to the basic Reponse type inorder to return. The full bankcard response object has more information you may want.
		var strResponse = RestHelper.GetResponse(request, isJson, false);
		if (strResponse.Contains("BankcardCaptureResponsePro") && isJson)
		{
			var response = RestHelper.GetCWSObjectListFromJson(strResponse);
			var list = response.Select(bankcardCaptureResponsePro => Utilities.SwapObjectsNamespace(bankcardCaptureResponsePro)).ToList();
			return ConvertToBasicResponseList(list);
		}
		else if (strResponse.Contains("BankcardCaptureResponse") && isJson)
		{
			var response = RestHelper.GetCWSObjectListFromJson(strResponse);
			var list = response.Select(bankcardCaptureResponse => Utilities.SwapObjectsNamespace(bankcardCaptureResponse)).ToList();
			return ConvertToBasicResponseList(list);  
		}
		else if(isJson)
		{
			var response = RestHelper.GetCWSObjectListFromJson(strResponse);
			var list = response.Select(captureResponse => Utilities.SwapObjectsNamespace(captureResponse)).ToList();
			return ConvertToBasicResponseList(list);  
		}
		else if (!isJson) // XML
		{
			return RestHelper.GetCWSObjectListFromXml(strResponse);
		}
	}
	catch (Exception ex)
	{
		RestFaultHandler.HandleFaultException(ex, isJson);
	}
}

 


 

CaptureAllAsync

The CaptureAllAsync operation is used to flag all transactions for settlement that have been successfully authorized using the Authorize operation without waiting for the settlement to complete.

Performing a CaptureAllAsync in Terminal Capture environments is advantageous since merchants don't need to wait for a response to the capture request. After settlement is complete, merchants can query the transactions in the batch using QueryBatch to determine the capture state of the batch.

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

SOAP

Operation

Response CaptureAllAsync(string sessionToken, List differenceData, List batchIds, string applicationProfileId, MerchantProfile merchantProfile, string merchantProfileId, string workflowId);

Parameters

Parameter Data Type Description
sessionToken String The short-lived token used to authenticate to CWS.
differenceData List<Capture> A list of one or more transactions to capture.
Note: You must send in BankcardCapture for Bankcard transactions.
batchIds List A list of one or more batch Ids to capture.
applicationProfileId String A token representing the PTLS Socket ID unique to each Service Key and configuration data combination. Returned by the SaveApplicationData operation.
merchantProfile MerchantProfile Conditional. The specific Merchant Profile to include in the transaction request. Required only if supporting Unmanaged Merchant Profiles (UMP).
merchantProfileId String The specific Merchant Profile Identifier to use.
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 Capture response data.
Note: For Bankcard (BCP) transactions, the response object is BankcardCaptureResponse.
For Electronic Checking (ECK) transactions, the response object is ElectronicCheckingCaptureResponse.
For Stored Value Account (SVA) transactions, the response object is StoredValueCaptureResponse.

Exceptions

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

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}
UMP URL https://api.cert.nabcommerce.com/REST/2.0.18UMP/Txn/{workflowId}
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.

Message Body Type

Data Type Description
Rest.CaptureAllAsync The message body containing transaction data.
Rest.CaptureAllAsyncWithProfile The message body containing transaction data and complete MerchantProfile required by UMP implementations.

Return Type

Data Type Description
List<Response> Capture response data.
Note: For Bankcard (BCP) transactions, the response object is BankcardCaptureResponse.
For Electronic Checking (ECK) transactions, the response object is ElectronicCheckingCaptureResponse.
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.

 


 

CaptureSelective

The CaptureSelective operation is used to flag a specific list of transactions (by transactionId) that have been successfully authorized using the Authorize operation or refunded using the Return* operations. When performing an Undo, the transaction will be removed from settlement processing so the transactionId of the Authorize or the Undo does not need to be passed when invoking the CaptureSelective operation.

Merchants may wish to invoke this operation to ensure only specific 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 CaptureSelective 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

SOAP

Operation

List CaptureSelective(string sessionToken, List transactionIds, List differenceData, string applicationProfileId, string workflowId);

Parameters

Parameter Data Type Description
sessionToken String The short-lived token used to authenticate to CWS.
transactionIds List A list of the specific transaction ids that should be captured.
Note: Return* transactions should be included. Undo transactions should be omitted.
differenceData List<Capture> A collection of capture details for one or more transactions.
Note: You must send in BankcardCapture 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
List<Response> A collection of capture response data.
Note: For Bankcard (BCP) transactions, the response object is BankcardCaptureResponse.
For Electronic Checking (ECK) transactions, the response object is ElectronicCheckingCaptureResponse.
For Stored Value Account (SVA) transactions, the response object is StoredValueCaptureResponse.

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 Samples

<?php
 require(dirname(__FILE__) . '/AuthOnly.php');
 
 /*
 *BankcardCapture Class needed for Capture
 */
 class BankcardCapture {
 public $Amount;
 public $ChargeType;
 public $ShipDate;
 public $TipAmount;
 public $TransactionId;
 public $Addendum;
 }
 
 $capture1 = new BankcardCapture();
 $capture1->TransactionId = $response[2];
 $capture1->ChargeType = 'NotSet';
 
 $ArrayOfTransactionIds = array($capture1->TransactionId);
 $ArrayOfCaptures = array($capture1);
 $transactionIds = '';
 foreach($ArrayOfTransactionIds as $key=>$val)
 {
 $transactionIds .= '<ns1:string xmlns:ns1="http://schemas.microsoft.com/2003/10/Serialization/Arrays">'. $val .'</ns1:string>';
 }
 
 $transactionCaptureSelective = '<?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>
 <CaptureSelective xmlns="http://schemas.ipcommerce.com/CWS/v2.0/TransactionProcessing">
 <sessionToken>'.$sessionTokenString.'</sessionToken>
 <transactionIds>'.
 $transactionIds
 .'</transactionIds>
 <differenceData xsi:nil="true"/>'
 .'<applicationProfileId>'.$applicationIdString.'</applicationProfileId>'
 .'<workflowId>'.$serviceId.'</workflowId>'
 .'</CaptureSelective>
 </SOAP-ENV:Body>
 </SOAP-ENV:Envelope>';
 
 $xmlRequest = $transactionCaptureSelective;
 $call = 'CaptureSelective';
 
 $responseVals = curl_call($xmlRequest, $sessionTokenString, $call);
 
 echo nl2br("<h1>CaptureSelective Transaction Results</h1>
 <h3>StatusMessage: " . $responseVals[0] . "</h3> 
 <h3>StatusCode: " . $responseVals[1] . "</h3> 
 <h3>TransactionId: " . $responseVals[2] . "</h3>
 ");
?>

C# Code Samples

public List CaptureSelective(string sessionToken, List transactionIds, List captures, string applicationProfileId, string workflowId)
{
	Type type = typeof(T);
 
	if (_msgFormat == MessageFormat.SOAP.ToString())
	{
		var bankcardCaptures = new List();
		var regularCaptures = new List();
		if (type == typeof(BankcardCapture))
		{
			foreach (var capture in captures)
			{
				bankcardCaptures.Add(capture as BankcardCapture);
			}
		}
		else
		{
			foreach (var capture in captures)
			{
				regularCaptures.Add(capture as Capture);
			}
		}
		using (var client = new CwsTransactionProcessingClient(ConfigurationManager.AppSettings["Bindings.TxnSoap"]))
		{
			try
			{
				if (bankcardCaptures.Count > 0)
					return client.CaptureSelective(sessionToken, transactionIds.ToArray(), bankcardCaptures.ToArray(), applicationProfileId, workflowId).ToList();
				return client.CaptureSelective(sessionToken, transactionIds.ToArray(), regularCaptures.ToArray(), applicationProfileId, workflowId).ToList();
			}
			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}
UMP URL https://api.cert.nabcommerce.com/REST/2.0.18UMP/Txn/{workflowId}
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.

Message Body Type

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

Return Type

Data Type Description
List<Response> A collection of capture response data.
Note: For Bankcard (BCP) transactions, the response object is BankcardCaptureResponse.
For Electronic Checking (ECK) transactions, the response object is ElectronicCheckingCaptureResponse.
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 Samples

/* NOTE: Do not pass in Undo or Authorize transactions that have had an Undo processed against it
 * $transactionIds are a list of transactions that you wish to settle
 * $differenceData is an object that contains any data to adjust at the time of settlement */
 
public function captureSelective($transactionIds, $differenceData, $creds = null)
{
	if (! $this->signOn ())
		return false;
		
	$DifferenceData = array ();
 
	if ($differenceData != null)
	{
		$i = 0;
		if (is_array ( $differenceData ))
		{
			foreach ( $differenceData as $diffData )
			{
				$Capture = new stdClass();
				$Capture->Type = 'REPLACE';
				$Capture->TransactionId = $diffData->transactionID;
				$Capture->Amount = $diffData->amount ? $diffData->amount : '0.00';
				$Capture->TipAmount = $diffData->tip_amount ? $diffData->tip_amount : '0.00';
				$Capture->ChargeType = 'NotSet';
				$Capture->ShipDate = date('Y-m-d\TH:i:s.u\Z');
				$DifferenceData [$i] = $Capture;
				$i++;
			}
		}
		else
		{
			$Capture = new stdClass ();
			$Capture->TransactionId = $diffData->transactionID;
			$Capture->Amount = $diffData->amount ? $diffData->amount : '0.00';
			$Capture->TipAmount = $diffData->tip_amount ? $diffData->tip_amount : '0.00';
			$DifferenceData [$i] = $Capture;
		}
		if ($creds != null) {
			$DifferenceData [0]->Addendum = new Addendum ();
			$DifferenceData [0]->Addendum->Unmanaged = new Unmanaged ();
			$DifferenceData [0]->Addendum->Unmanaged->Any = new Any ();
			$DifferenceData [0]->Addendum->Unmanaged->Any->string = $creds;
		}
	}
 
	$CapType = '"$type":"CaptureSelective,http://schemas.nabcommerce.com/CWS/v2.0/Transactions/Rest",';
	$DiffType = '"$type":"BankcardCapture,http://schemas.nabcommerce.com/CWS/v2.0/Transactions/Bankcard",';
 
	// Build Capture
	$msgBody = new Rest_CaptureSelective ();
	$msgBody->ApplicationProfileId = $this->appProfileID;
	$msgBody->TransactionIds = $transactionIds;
	$msgBody->DifferenceData = $DifferenceData;
 
	$action = 'PUT';
	$url = $this->txn.'/'.$this->workflowId;
 
	// Format the message
	$diffString = '"Type":"REPLACE",';
	$msgBody = (string)json_encode($msgBody);
	$msgBody = str_replace('{"ApplicationProfileId"', '{'.$CapType.'"ApplicationProfileId"', $msgBody);
	$msgBody = str_replace($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 Samples

public List CaptureSelective(string sessionToken, List transactionIds, List captures, string applicationProfileId, string workflowId)
{
	var isJson = string.Equals(_msgFormat, MessageFormat.JSON.ToString());
	var requestString = RestBaseUri + "/" + workflowId;
	var restCaptureSelective = new schemas.nabcommerce.com.CWS.v2._0.Transactions.Rest.CaptureSelective();
	restCaptureSelective.ApplicationProfileId = applicationProfileId;
	// For Capture Selective in REST DifferenceData maybe set to null unless there is a change in the transaction since authorization.
	restCaptureSelective.DifferenceData = null;
	restCaptureSelective.TransactionIds = transactionIds;
 
	var request = RestHelper.CreateRestRequest(restCaptureSelective, requestString, HttpMethod.PUT, sessionToken, isJson);
	try
	{
		// The response is an array of specific capture response. First step is to get the CWS Object from the list. 
		// With JSON the conversion needs the fully typed namespace. 
		// After that it is coverted to the shorter namespace defined by the service reference. 
		// The last step converts this list to the basic Reponse type inorder to return. The full bankcard response object has more information you may want.
		var strResponse = RestHelper.GetResponse(request, isJson, false);
		if (strResponse.Contains("BankcardCaptureResponsePro") && isJson)
		{
			var response = RestHelper.GetCWSObjectListFromJson(strResponse);
			var list = response.Select(bankcardCaptureResponsePro => Utilities.SwapObjectsNamespace(bankcardCaptureResponsePro)).ToList();
			return ConvertToBasicResponseList(list);
		}
		else if (strResponse.Contains("BankcardCaptureResponse") && isJson)
		{
			var response = RestHelper.GetCWSObjectListFromJson(strResponse);
			var list = response.Select(bankcardCaptureResponse => Utilities.SwapObjectsNamespace(bankcardCaptureResponse)).ToList();
			return ConvertToBasicResponseList(list);
		}
		else if (isJson)
		{
			var response = RestHelper.GetCWSObjectListFromJson(strResponse);
			var list = response.Select(captureResponse => Utilities.SwapObjectsNamespace(captureResponse)).ToList();
			return ConvertToBasicResponseList(list);
		}
		else if (!isJson) // XML
		{
			return RestHelper.GetCWSObjectListFromXml(strResponse);
		}
	}
	catch (Exception ex)
	{
		RestFaultHandler.HandleFaultException(ex, isJson);
	}
}

 


 

CaptureSelectiveAsync

The CaptureSelectiveAsync operation is used to flag a specific list of transactions (by transactionId) for settlement that have been successfully authorized using the Authorize operation or refunded using the Return* operations. When performing an Undo, the transaction will be removed from settlement processing so the transactionId of the Authorize or the Undo does not need to be passed when invoking the CaptureSelectiveAsync operation.

Performing a CaptureSelectiveAsync in Terminal Capture environments is advantageous since merchants don't need to wait for a response to the capture request. After settlement is complete, merchants can query the transactions in the batch using QueryBatch to determine the capture state of the batch.

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

SOAP

Operation

Response CaptureSelectiveAsync(string sessionToken, List transactionIds, List differenceData, string applicationProfileId, string workflowId);

Parameters

Parameter Data Type Description
sessionToken String The short-lived token used to authenticate to CWS.
transactionIds List A list of the specific transaction ids that should be captured.
Note: Return* transactions should be included. Undo transactions should be omitted.
differenceData List<Capture> A collection of capture details for one or more transactions.
Note: You must send in BankcardCapture 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 Capture response data.
Note: For Bankcard (BCP) transactions, the response object is BankcardCaptureResponse.
For Electronic Checking (ECK) transactions, the response object is ElectronicCheckingCaptureResponse.
For Stored Value Account (SVA) transactions, the response object is StoredValueCaptureResponse.

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.

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}
UMP URL https://api.cert.nabcommerce.com/REST/2.0.18UMP/Txn/{workflowId}
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.
transactionIds List The transaction IDs to capture.

Message Body Type

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

Return Type

Data Type Description
List<Response> Capture response data.
Note: For Bankcard (BCP) transactions, the response object is BankcardCaptureResponse.
For Electronic Checking (ECK) transactions, the response object is ElectronicCheckingCaptureResponse.
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.

Comments