SOAP API Reference

Print Friendly, PDF & Email

Refund Transaction (SOAP)

 

The ReturnById operation is used to perform a linked credit to a cardholder’s account from the merchant’s account based on a previously authorized and settled transaction.

Note: In the Return differenceData object, the Amount parameter represents the amount to be credited back to the cardholder.
 

For example:

Captured Amount = $10.00; ReturnById Amount = $4.00; Settled Amount = $6.00 ($4.00 was returned to the customer, $6.00 remains in the merchant account) Captured Amount = $10.00; ReturnById Amount = $12.00 ERROR: Cannot return for more than the original captured amount.
 

Operation

Response ReturnById(string sessionToken, Return differenceData, string applicationProfileId, string workflowId);
 

Parameters

Parameter Data Type Description
sessionToken String The limited-life token used to authenticate to CWS.
differenceData Return Contains the return details based on the original authorized and captured amount.Note: You must send in BankcardReturn 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 serviceIdreturned 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 ReturnById(string sessionToken, Return differenceData, string applicationProfileId, string workflowId)
{
  using (var client = new CwsTransactionProcessingClient(ConfigurationManager.AppSettings["Bindings.TxnSoap"]))
  {
    try
    {
      return client.ReturnById(sessionToken, differenceData, applicationProfileId, workflowId);
    }
    catch (FaultException ex)
    {
      SoapFaultHandler.HandleFaultException(ex);
    }
  }
}
/* $transactionID is the known transaction ID of a previous transaction
 * $amount is the amount of money to return, leave it empty to return full amount*/

public function returnByID($transactionID, $creds = null, $amount = null)
{
  if (! $this->signOn ())
    return false;

  $return_amount = new BankcardReturn ();
  $return_amount->Amount = $amount;
  $return_amount->TransactionId = $transactionID;
  if ($creds != null)
  {
    $return_amount->Addendum = new Addendum ();
    $return_amount->Addendum->Unmanaged = new Unmanaged ();
    $return_amount->Addendum->Unmanaged->Any = new Any ();
    $return_amount->Addendum->Unmanaged->Any->string = $creds;
  }

  // Build ReturnById
  $trans = new ReturnById ();
  $trans->sessionToken = $this->session_token;
  $trans->transactionId = $transactionID;
  $trans->differenceData = $return_amount;
  $trans->merchantProfileId = $this->merchantProfileID;
  $trans->workflowId = $this->workflowId;
  $trans->applicationProfileId = $this->appProfileID;

  try
  {
    $response = $this->bankCard->ReturnById ( $trans )->ReturnByIdResult;
    /*echo 'RETURNBYID: 
';
     echo ('
'.$this->bankCard->__getLastRequestHeaders());*/
    //echo ('
'.$this->bankCard->__getLastRequest());
    /*echo ('
'.$this->bankCard->__getLastResponseHeaders());
     echo ('
'.$this->bankCard->__getLastResponse());*/
    return $response;
  }
  catch ( SoapFault $e )
  {
    echo 'SERVER ERROR: Error trying to Return By ID.
';
    //echo ('
'.$this->bankCard->__getLastRequest());
    //echo ('
'.$this->bankCard->__getLastResponse());
    $xmlFault = $this->bankCard->__getLastResponse ();
    $errors = handleTxnFault ( $e, $xmlFault );
    echo $errors;
    exit ();
  }
}

The ReturnUnlinked operation is used to perform an “unlinked”, or standalone, credit to a cardholder’s account from the merchant’s account. This operation is useful when a return transaction is not associated with a previously authorized and settled transaction.

  

Operation

Response ReturnUnlinked(string sessionToken, Transaction transaction, string applicationProfileId, MerchantProfile merchantProfile, 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 BankcardTransaction 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.
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 ReturnUnlinked(string sessionToken, Transaction transaction, string applicationProfileId, string merchantProfileId, string workflowId)
{
  using (var client = new CwsTransactionProcessingClient(ConfigurationManager.AppSettings["Bindings.TxnSoap"]))
  {
    try
    {
      return client.ReturnUnlinked(sessionToken, transaction, applicationProfileId, merchantProfileId, workflowId);
    }
    catch (FaultException ex)
    {
      SoapFaultHandler.HandleFaultException(ex);
    }
  }
}
/* NOTE: See Authorize/AuthorizeAndCapture for structure */

public function returnUnlinked($credit_info, $trans_info)
{
  if (! $this->signOn ())
    return false;

  // Bank Transaction
  $bank_trans = buildTransaction ( $credit_info, $trans_info );

  // Build Return Unlinked
  $trans = new ReturnUnlinked ();
  $trans->sessionToken = $this->session_token;
  $trans->transaction = $bank_trans;
  $trans->merchantProfileId = $this->merchantProfileID;
  $trans->workflowId = $this->workflowId;
  $trans->applicationProfileId = $this->appProfileID;

  try
  {
    $response = $this->bankCard->ReturnUnlinked ( $trans )->ReturnUnlinkedResult;
    //echo ('
'.$this->bankCard->__getLastRequest());
    return $response;
  }
  catch ( SoapFault $e )
  {
    echo 'SERVER ERROR: Error trying to Return Unlinked.';
    $xmlFault = $this->bankCard->__getLastResponse ();
    $errors = handleTxnFault ( $e, $xmlFault );
    echo $errors;
    exit ();
  }
}