AutoBill.settlementQuote

The settlementQuote method generates a quote for the settlement amount that would result from an AutoBill.cancel call made with both the disentitle and settle parameters set to True. You can then provide your customers this preview of how much prorated amount would be refunded upon cancellation and, if the customer agrees, commit the cancellation.

Additionally, advance knowledge of how much would be subject to refund can guide your refund policy decisions for allowing immediate disentitlement and/or choosing to settle.

Input

srd: sparse response description, a SOAP string (which must be a JSON object), in which you specify the elements you want returned.This parameter enables the calling system to constrain a method call to return only components you specify. This gives you greater control over returned content, and improves response time within the Vindicia platform by reducing the processing needed for the call. 

Some fields are required, either practically or in the WSDL, and will be returned regardless of the srd. A null srd returns the complete response.

autobill: the AutoBill object for which the quote is to be generated. You can identify this object with either its VID or your AutoBill ID (merchantAutoBillId). 

force: a Boolean flag that, when set to true, forces generation of a quote even if the minimum commitment period for this AutoBill object has not yet been satisfied. 

amountOnly: a Boolean flag that, when set to true, restricts the output to just the settlement amount. When set to false, or not specified, settlementQuote will also generate mock Refunds/Transactions that would be generated in response to an actual AutoBill.cancel call with disentitle and settle parameters set. 

Output

amount: Settlement amount (Decimal). Negative for Refund, Positive for charge.

currency: ISO 4217 currency code for amount.

token: Vindicia Token for amount when the AutoBill uses a Token BillingPlan / PayementMethod). 

note: a string providing additional information about the success or failure of the settlement quote.

transactions: An array of Transaction objects that provide details of the charges the customer will incur with the settlement.

refunds: An array of Refund objects that provide details of credits that will be refunded to the customer with the settlement.

Returns

In addition to those returned in Standard Return Codes, this call returns:

Return Code	Return String
	One of the following:
200	Sucess
400	AutoBill was not specified Error processing settlement quote request: [Failure Details]
403	Settlement quote attempt failed (Usually a soft failure, such as the tax vendor being down) Minimum commitment not fulfilled for this AutoBill
405	Cannot cancel Upgraded AutoBill
500	Something went terribly wrong (SYSERROR)

 

Example

 

$autobillVid = 'ffff2d063iamnotanalien96a284234b006d7b7c'; // for illustration purposes only!

$autobill_factory = new autobill();

 

//Fetch existing AutoBill

$response = $autobill_factory->fetchByVid($autobillVid);

if($response['returnCode'] == 200) 

{

  $autobill = $response['autobill'];

  $force = true;

  $amount_only = false;

 

  //Make settlementQuote request

  $response = $autobill_factory->settlementQuote(

                      $autobill,      // Vindicia::Soap::AutoBill

                      $force,         // xsd:boolean

                      $amount_only    // xsd:boolean

                      );

  if($response['returnCode'] == 200)

  {

    $settlement_amount = $response['amount'];            

                            // Settlement quote amount (negative for credit)

    $settlement_currency = $response['currency'];        

                            // ISO 4217 Currency code

    @settlement_transactions = $response['transactions'];

                            // Array of Vindicia::Soap::Transaction objects

    @settlement_refunds = $response['refunds'];          

                            // Array of Vindicia::Soap::Refund objects

    $settlement_note = $response['note'];                

                            // String providing note on quote attempt

  }

  else

  {

    // Handle settlementQuote failure

  }

}

else

{

  // Handle fetchByVid failure

}