API Docs
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.
The Adjust operation is used to make adjustments to a previously authorized amount (incremental or reversal) prior to capture and settlement.
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 |
Response Adjust(string sessionToken, Adjust differenceData, string applicationProfileId, string workflowId);
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. |
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. |
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
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>
");
?>
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);
}
}
}
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.
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 |
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. |
Data Type | Description |
Rest.Adjust | The message body containing transaction data. |
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. |
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.
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);
}
}
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.
Response Undo(string sessionToken, Undo differenceData, string applicationProfileId, string workflowId);
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. |
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. |
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
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>
");
?>
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);
}
}
}
Note:The HTTP Authorization Header must contain the required sessionToken value.
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 |
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. |
Data Type | Description |
Rest.Undo | The message body containing transaction data. |
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. |
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.
/* 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];
}
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);
}
}
Updated: June 2, 2017
SUBMIT A DEVELOPER SUPPORT REQUEST
Agent or a merchant? Contact NAB support at 866.485.8999 EXT 2341