Authorize Transaction (SOAP)

SOAP API Reference

Authorize Transaction (SOAP)

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.

 

Authorize

The following operations are used to authorize transactions for SOAP implementations:

 

Operation

Response Authorize(string sessionToken, Transaction transaction, string applicationProfileId, <em>MerchantProfile merchantProfile</em>, string merchantProfileId, string workflowId);

 

Parameters

Parameter Data Type Description
sessionToken String The limited-life token used to authenticate to CWS.
transaction Transaction Transaction detail data.
Note: You must send in BankcardTransactionfor 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.
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 serviceId returned by GetServiceInformation.

 

Return Type

Data Type Description
Response Transaction response data.
Note: For Bankcard (BCP) transactions, the response object is BankcardTransactionResponsePro.

 

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.

 

Code Snippets

public Response Authorize(string sessionToken, Transaction transaction, string applicationProfileId, string merchantProfileId, string workflowId)
{
  var isJson = string.Equals(_msgFormat, MessageFormat.JSON.ToString());
  var requestString = RestBaseUri + "/" + workflowId;
  var restAuthTxn = new AuthorizeTransaction();
  restAuthTxn.ApplicationProfileId = applicationProfileId;
  restAuthTxn.MerchantProfileId = merchantProfileId;

  // Since 'transaction' references the service reference, this needs to be converted to use the Generated Proxie data contracts.
  // If using REST this step should be avoided by using the generated proxies directly throughout your application.
  Type type = transaction.GetType();
  if(type == typeof(BankcardTransaction))
    restAuthTxn.Transaction = Utilities.SwapObjectsNamespace(transaction);
  else if (type == typeof(BankcardTransactionPro))
    restAuthTxn.Transaction = Utilities.SwapObjectsNamespace(transaction);
  else if (type == typeof(ElectronicCheckingTransaction))
    restAuthTxn.Transaction = Utilities.SwapObjectsNamespace(transaction);
  else if (type == typeof(StoredValueTransaction))
    restAuthTxn.Transaction = Utilities.SwapObjectsNamespace(transaction);
  else if (type == typeof(Transaction))
    restAuthTxn.Transaction = Utilities.SwapObjectsNamespace(transaction);

  var request = RestHelper.CreateRestRequest(restAuthTxn, requestString, HttpMethod.POST, sessionToken, isJson);
  try
  {
    if(isJson) 
      return RestHelper.GetResponse(request, isJson);
    // For XML the specifc expect response needs to be passed so that it can be deserialized properly. 
    if (type == typeof(BankcardTransactionPro) || type == typeof(BankcardTransaction))
      return RestHelper.GetResponse(request, isJson);
    if (type == typeof(ElectronicCheckingTransaction))
      return RestHelper.GetResponse(request, isJson);
    if (type == typeof(StoredValueTransaction))
      return RestHelper.GetResponse(request, isJson);
  }
  catch (Exception ex)
  {
    RestFaultHandler.HandleFaultException(ex, isJson);
  }
}
/* $trans_info is class type transData
 * $amount and $tip_amount: ('#.##'} (At least $1, two decimals required (1.00))*/

public function authorize($credit_info, $trans_info, $processAsPro = false)
{
  if (! $this-&gt;signOn ())
    return false;

  if ($this-&gt;svc instanceof BankcardService || $this-&gt;svc == null)
  {
    // Bank Transaction Pro
    if ($processAsPro == true)
    {
      $Transaction = buildTransactionPro ( $credit_info, $trans_info );
      $TxnType = '"$type":"BankcardTransactionPro,http://schemas.ipcommerce.com/CWS/v2.0/Transactions/Bankcard/Pro",';
      $TxnDataType = '"$type":"BankcardTransactionDataPro,http://schemas.ipcommerce.com/CWS/v2.0/Transactions/Bankcard/Pro",';
    }
    // Bank Transaction
    else
    {
      $Transaction = buildTransaction ( $credit_info, $trans_info );
      $TxnType = '"$type":"BankcardTransaction,http://schemas.ipcommerce.com/CWS/v2.0/Transactions/Bankcard",';
      $TxnDataType = '"$type":"BankcardTransactionData,http://schemas.ipcommerce.com/CWS/v2.0/Transactions/Bankcard",';
    }
  }
  if ($this-&gt;svc instanceof ElectronicCheckingService)
  {
    $Transaction = buildACHTransaction($credit_info, $trans_info);
    $TxnType = '"$type":"ElectronicCheckingTransaction,http://schemas.ipcommerce.com/CWS/v2.0/Transactions/ElectronicChecking",';
    $TxnDataType = '"$type":"ElectronicCheckingTransactionData,http://schemas.ipcommerce.com/CWS/v2.0/Transactions/ElectronicChecking",';
  }

  $msgBody = new Rest_AuthorizeTransaction();
  $msgBody-&gt;ApplicationProfileId = $this-&gt;appProfileID;
  $msgBody-&gt;MerchantProfileId = $this-&gt;merchantProfileID;
  $msgBody-&gt;Transaction = $Transaction;
  $action = 'POST';
  $url = $this-&gt;txn.'/'.$this-&gt;workflowId;

  // Format the message
  $txnString = '"Transaction":{';
  $txnDataString = '"TransactionData":{';
  $msgBody = (string)json_encode($msgBody);
  $msgBody = str_replace('{"ApplicationProfileId"', '{"$type":"AuthorizeTransaction,http://schemas.ipcommerce.com/CWS/v2.0/Transactions/Rest","ApplicationProfileId"', $msgBody);
  $msgBody = str_replace($txnString, $txnString.$TxnType, $msgBody);
  $msgBody = str_replace($txnDataString, $txnDataString.$TxnDataType, $msgBody);
  $msgBody = str_replace(' ', '', $msgBody); // Make sure no spaces remain in the body.
  $response = curl_json($msgBody, $url, $action, $this-&gt;session_token);
  if(isset($response-&gt;body-&gt;ErrorId))
  {
    handleRestFault($response);
    return false;
  }
  if(isset($response[2]))
    return $response[2];
}

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.