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.

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

Return Type

Exceptions

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->signOn ())
    return false;

  if ($this->svc instanceof BankcardService || $this->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->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->ApplicationProfileId = $this->appProfileID;
  $msgBody->MerchantProfileId = $this->merchantProfileID;
  $msgBody->Transaction = $Transaction;
  $action = 'POST';
  $url = $this->txn.'/'.$this->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->session_token);
  if(isset($response->body->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.