SCS Cancel Contract API

Overview

The SCS Auto Platform provides a web service that allows external systems (Integration Partners) to validate and execute cancel contract transactions electronically. The web service will verify all the business rules necessary to execute the transaction, and if these are met will execute the transaction. If any business rules are not met the web service will specify these in the error/warning response.

This document addresses the methods ValidateCancelContract and CancelContract that allow validation and execution of cancel contract transactions. The ValidateCancelContract method can be used to validate a cancel contract transaction and verify all business rules in SCS without executing the cancel contract transaction. If any business rules are not met, then the response will specify what, if any, are not met. This will enable requestors to know exactly what data elements to fix such that these transactions can be resubmitted to the CancelContract method to be successfully processed. The CancelContract method also verifies all business rules and specifies all error messages if there are any issues; further, if the CancelContract request is valid, it will go ahead and cancel the contract as well.

SCS Web Service Specifications

Data Format

The following table represents the data formats used in the XML coding (Use to reference the “Format” column in the XML schema tables defined in this document)

Data type	Description	Example
X(10)	Characters of max length of 10	ABCDEABCDE
Date	yyyy-mm-dd	2000-12-21
DateTime	yyyy-mm-ddThh:mm:ss	2000-12-21T12:24:40
N(5)	Number,max length of 5	12345
N(8,2)	Number with two decimals, max length of 8.	123456.78
Boolean	Boolean true or false	true

Validation

1. The same function that either Cancels active/expired contracts or Voids pending not billed contracts from SCS and DAP will be called when a request is received. All SCS business rules built into the cancellation/void module will be applied to the contract based on the inputs provided and the contract’s current state.
2. CancelContract will validate and execute the following transactions based on the contract’s status:
   • Cancel - if the contract is in Active or Expired status
   • Void - if the contract is in Pending not billed status and the cancel date is equal to the contract sale date
3. The request schema must include a CancellationReason. When a contract is to be cancelled, the Cancellation reason will be matched to the Preference Manager configuration.
4. The request schema must include a DealerNumber.
5. The plan associated to the contract determines the cancellation rule and the cancellation defaults will determine the payee, calculation basis and pay method.
   • See #1 in section 'SCS-2290 Updates' for additional details on ability to specify an alternate cancellation payee.
6. When the ValidateCancelContract request is received and the contract is active/expired, then the response will include a cancel quote id and quote rates for a successful cancel response. The cancel quote id which is required in the CancelContract request will be stored in SCS just as cancellation quotes are stored when DAP users request a cancel quote. The ValidateCancelContract response when ‘Successful’ will include the CancelContract request that can be used to subsequently perform the CancelContract transaction.
   • An additional note will be generated in SCS as a result of a successful cancel validation request: ‘Cancel Quote from the web service’. This will follow the current note generated from SCS: ‘Cancellation Quote: On < cancellation date > Odometer at < cancellation odometer >.’
7. When the ValidateCancelContract request includes a quote Id the validation will fail and an error message will indicate that an additional quote needs to be created:
   • If the request values differ from the stored cancel quote values (Example: CancellationOdometer in the request is different than the CancellationOdometer in the stored quote)
   • If the cancellation quote rates changed
8. The CancelContract request which includes a quote Id will fail validation and return an error message that an additional quote needs to be created:
   • If the request values differ from the stored cancel quote values (Example: CancellationOdometer in the request is different than the CancellationOdometer in the stored quote)
   • If the cancellation quote rates have changed
9. When the CancelContract request is sent to cancel an active/expired contract, the contract will be cancelled if it meets all the contract cancellation business rules. Upon cancellation an additional note will be generated in SCS with Cancel information as a result of a successful cancel request:
   • 'Contract status changed via ContractCancel web service.'
   • The userid is recorded with the note
10. When the CancelContract request is sent to cancel a pending not billed contract, the contract will be void if it meets all the contract void business rules. Upon void an additional note will be generated in SCS with Void information as a result of a successful cancel request:
    • 'Contract status changed via ContractCancel web service.'
    • The userid is recorded with the note
11. Locking on Validate and CancelContract request:
    • If at validation the contract is locked the response object will return a ResponseCode=0 and a ‘Contract is locked’ error message.
12. Actions that require Underwriting Supervisor permission will not be performed by any of the webservice methods

SCS-22900 Updates

1. The cancellation refund payment can be issued to a party other than the configured default cancellation payee by specifying the Cancellation Refund Payee Type (CancelRefundPayeeType) and optionally, the Cancellation Calculation Basis (CancelCalcBasis) in the CancelContract request.
   1. The CancelRefundPayeeType can be specified to override the configured default cancellation payee.
   2. The CancelCalcBasis can be specified to override the specified cancellation payee’s calc basis (Net/Retail) rules.
      • Web service user must have the permission ‘User Can OVERWRITE Payee NET/Retail rules’.
      • If the CancelCalcBasis is not specified in the request, the configured Calc Basis for the payee type will be used.
      • Based on the payee type selected, the corresponding payee will be selected based on the contract information (e.g., agent, lienholder, customer or seller).
   3. If both tags are empty, the configured default cancellation payee and calc basis are used.

CancelContract Request Schema

CancelContractRequest Object

Tag	Format	Cancel Req/Opt/ Cond	Attrib	Valid values	Description
TpaCode	X(4)	R			Third Party Administrator Code
UserId	X(30)	R			User ID issued to the requesting system
Password	X(255)	R			Password issued to the requesting system
CancelQuoteID	N(15)	C	nillable		Unique identifier that identifies the cancel quote generated for a successful cancel validation. The quote id will be used to proceed with the actual cancellation. Optional for ValidateCancelContract request. Required for CancelContract request
ContractNumber	X(20)	R			Contract Number to be validated for cancel or void.
DealerNumber	X(18)	R			Dealer Number
CancellationOdometer	N(7)	C			Odometer at the time of cancellation Required if contract status is ‘Active’ or ‘Expired’ and it is required per the configured cancel calculation method
CancellationDate	Date	R			Date the cancellation becomes effective Required if contract status is ‘Active’ or ‘Expired’ Required to Void a ‘Pending’ not billed contract
CancellationReason	X(100)	R			Reason for cancellation. Must be one of the cancellation reasons defined in SCS Preference manager.
CancelRefundPayeeType	N(1)	C			Cancellation payee type: 1 = Seller, 2 = Customer, 3 = Lienholder, 4 = Customer And Lienholder, 5 = Lienholder And Customer, 6 = Agent. (CancelRefundPayeeType of 5 = Other will not be supported). Required if the cancellation refund payee is not based on cancellation Defaults configuration
CancelCalcBasis	T(1)	C			Cancel Calc Basis, either Net Or Retail (‘N’ or ‘R’) Required if the cancellation refund payee is not based on cancellation Defaults configuration. If CancelRefundPayeeType = 1 (Seller), ‘N’ is the only permitted value.

Sample Soap Request

SOAPAction: "<http://tempuri.org/ContractService/ValidateCancelContract>"
<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope xmlns:xsi="<http://www.w3.org/2001/XMLSchema-instance>" xmlns:xsd="<http://www.w3.org/2001/XMLSchema>" xmlns:soap="<http://schemas.xmlsoap.org/soap/envelope/>">
<soap:Body>
    <ValidateCancelContract xmlns="<http://tempuri.org/ContractService/>">
        <request>
            <CancelQuoteId>int</CancelQuoteId>
            <ContractNumber>string</ContractNumber>
            <DealerNumber>string</DealerNumber>
            <CancellationOdometer>int</CancellationOdometer>
            <CancelationDate>dateTime</CancelationDate>
            <CancellationReason>string</CancellationReason>
            <CancelRefundPayeeType>string</CancelRefundPayeeType>
            <CancelCalcBasis>string</CancelCalcBasis>
        </request>
    </ValidateCancelContract>
</soap:Body>
</soap:Envelope>

SOAPAction: "<http://tempuri.org/ContractService/CancelContract>"
<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope xmlns:xsi="<http://www.w3.org/2001/XMLSchema-instance>" xmlns:xsd="<http://www.w3.org/2001/XMLSchema>" xmlns:soap="<http://schemas.xmlsoap.org/soap/envelope/>">
    <soap:Body>
        <CancelContract xmlns="<http://tempuri.org/ContractService/>">
            <request>
                <CancelQuoteId>int</CancelQuoteId>
                <ContractNumber>string</ContractNumber>
                <DealerNumber>string</DealerNumber>
                <CancellationOdometer>int</CancellationOdometer>
                <CancelationDate>dateTime</CancelationDate>
                <CancellationReason>string</CancellationReason>
                <CancelRefundPayeeType>string</CancelRefundPayeeType>
                <CancelCalcBasis>string</CancelCalcBasis>
            </request>
        </CancelContract>
    </soap:Body>
</soap:Envelope>

CancelContract Response Schema Details

The response schema for ValidateCancelContract when ‘Successful’ will include the CancelContract request that can be used to subsequently perform the CancelContract transaction.

ValidateCancelContractResponse Object

Tag	Content Items	Format	Description
ValidateCancelContract
	ValidateCancelContractResult
	ResponseCode		1 = Successful, ValidateCancelContract passed 0 = ValidateCancelContract failed see Message Object for Type
	CancelQuoteID	N(15)	Unique identifier that identifies the cancel quote generated for a successful cancel validation. The quote id will be used in the CancelContract request to proceed with the actual cancellation.
	RetailCost	N(8,2)	Original Retail Cost
	NetCost	N(8,2)	Original Net Cost
	NonRefundablefee	N(8,2)	Customer Non Refundable Fee
	CancelFee	N(8,2)	Cancel Fee
	NetRefundfromAdmin	N(8,2)	Net Refund from Admin
	RefundfromSeller	N(8,2)	Refund from Seller
	CancelRefundAmount	N(8,2)	Cancel Refund Amount
	CancelFactorTermPercent	N(6,5)	Cancel Factor Term Percentage
	CancelFactorMileagePercent	N(6,5)	Cancel Factor Mileage Percentage
	CancelFactorPercent	N(6,5)	Cancel Factor Percentage applied
	CalculationMethod	N(80)	Cancel Calculation Method
	CalculationMethodCode	X(10)	Cancel Calculation Method Code
	Messages	Message Object	Collection of Messages.
	CancelContract	CancelContract Request Object	The response schema for ValidateCancelContract when ‘Successful’ will include the CancelContract request that can be used to subsequently perform the CancelContract transaction.

CancelContractResponse Object

Tag	Content Items	Format	Description
CancelContract
	CancelContractResult
	ResponseCode		1 = Successful, Cancel Contract passed; 0 = Cancel Contract validation failed. See Message Object for Type
	CancelQuoteID	N(15)	Unique identifier that identifies the cancel quote generated for a successful cancel validation.
	RetailCost	N(8,2)	Original Retail Cost
	NetCost	N(8,2)	Original Net Cost
	NonRefundablefee	N(8,2)	Customer Non Refundable Fee
	CancelFee	N(8,2)	Cancel Fee
	NetRefundfromAdmin	N(8,2)	Net Refund from Admin
	RefundfromSeller	N(8,2)	Refund from Seller
	CancelRefundAmount	N(8,2)	Cancel Refund Amount
	CancelFactorTermPercent	N(6,5)	Cancel Factor Term Percentage
	CancelFactorMileagePercent	N(6,5)	Cancel Factor Mileage Percentage
	CancelFactorPercent	N(6,5)	Cancel Factor Percentage applied
	CalculationMethod	X(80)	Cancel Calculation Method
	CalculationMethodCode	X(10)	Cancel Calculation Method Code
	Messages	Message Object	Collection of Messages.

Message Object

Tag	Format	Req/Opt/ Cond	Valid values	Description
Type	Integer	R	1 = Error, 2 = Info, 3 = Warning, 4 = Success	Message Type
Code	String, X(30)	R		Returns the associated code with each message text.
Text	String, X(2000)	R		Message Text

Error Messages

CancelContract Error Messages

Message Type	Error Code	Message Text
Error	rfvTPACode	TPA Code is required.
Error	VD0003	TPA is invalid.
Error	ERRSESSION	Unable to create session.
Error	WSLICEN001	License not available.
Error	VD0009	Authentication Failed.
Error	WSSECUR001	You do not have necessary permission to execute this web method.
Error	rfvContractNumber	Contract Number is required.
Error	rfvDealerNumber	Seller Number is required.
Error	CAN_008	Cancellation reason is required.
Error	CAN_007	Cancellation Date is required.
Error	VD0001	Invalid contract number.
Error	DLRNOTEXIST	Dealer does not exist.
Error	VD0006	Only selling dealer can void contracts.
Error	CAN_001	Only selling dealer can cancel contracts.
Error	CAN_002	Invalid Cancellation Reason.
Error	CAN_012	Cancellation odometer is required.
Error	CAN_011	Void cannot be processed - Contract is in Pending status, but cancel date does not equal sale date.
Error	VD0014	Contract # {0} is locked by another user. Please unlock the contract before making changes.
Error	CAN_018	Contract could not be cancelled. Contract is locked for editing.
Error	CAN_019	Contract could not be voided. Contract is locked for editing.
Error	VOID_CONTRACT_BILLED	This contract cannot be voided because it has been billed.
Error	CLAIMS_OPEN	The contract has open claim(s).
Error	CLAIMS_OPEN_FAIL	Unable to verify open claim(s).
Error	VOID_CLAIMS_OPEN	The contract cannot be voided due to open claim(s).
Error	invldcyclmthrng	Invalid cycle month range.
Error	SAVEFAIL	Cannot save record.
Error	PAYOPTSAVEFAIL	Cannot save payment option
Error	DEL_CONTRACT_RELATION_FAIL	Cannot delete contract's relations.
Error	CONTRACT_VOID_FAIL	Cannot Void Contract.
Error	CAN_014	Cancellation cannot be processed. Contract is in {0} status.
Error	UNAPPLIED_CRD	Unapplied credit exists for this contract. The credit must be refunded or applied to a debit transaction in order to cancel contract.
Error	CAN_013	Cancellation Quote ID is required.
Error	CAN_004	Invalid Cancellation Quote Id.
Error	CAN_003	Cancellation Odometer does not match odometer from the quote. Create an additional quote.
Error	CAN_005	Cancellation Date does not match date from the quote. Create an additional quote
Error	CAN_020	Cancellation Reason does not match reason from the quote. Create an additional quote.
Error	CCBPNOTSET_1	Contract cannot be cancelled due to a cancellation configuration issue. Please contact your contract administrator for assistance. SCS-22900 – The same message will be used with the CancelRefundPayeeType = 7 (Agent), but there is no agent on the contract.
Error	CANLHNSET_1	Contract cannot be cancelled because the contract does not have a Lienholder SCS-22900 – The same message will be used with the CancelRefundPayeeType is 3 (Lienholder), 4 (Customer and Lienholder) or 6 (Lienholder and Customer), but there is no lienholder on the contract.
Error	CANLHADDR_1	Contract cannot be cancelled because the Lienholder does not have an address. SCS-22900 – The same message will be used with the CancelRefundPayeeType is 3 (Lienholder), 4 (Customer and Lienholder) or 6 (Lienholder and Customer), but the lienholder on the contract does not have an address configured.
Error	CancelDateGreater	Cancel date cannot be greater than today.
Error	CANCELDATE_GT_EXPDATE	The cancellation date is greater than contract expiration date.
Error	CancelContractDate	Cancellation date must be on or after contract sale date ( {0} ).
Error	CancelLessSaleOdom	Cancellation odometer cannot be less than sale odometer.
Error	CancelDateNoContract	Cancellation date range is not defined for contract type. Contract Type: {0}
Error	CancelDateNoCancel	Cancellation date range is not defined for the cancellation rule.Rule Name: {0}
Error	CancStateRuleNotDefined1	Cancellation rules are not defined for the insured state. Insured State: Rule Type: Custom Rule Name
Error	CancStateRuleNotDefined2	Cancellation rules are not defined for the insured state. Insured State: Rule Type: Default Contract Type
Error	ERRLOADCANCLMTHD	Error loading Cancellation Method
Error	CAN_017	Contract has an open claim. Cancellation odometer must be equal to or greater than last reported claim odometer {0}
Error	CANCBNIMP	Cancellation Calculation Base not implemented
Error	CANRFGRNT	Refund Amount provided can not be greater than {0} Rate plus Tax or less than $0
Error	CAN_021	Incorrect Cancellation Method. The Calculation Method is configured to use Mileage factor, instead of Term factor.
Error	ContractOpenDeductClaim	The contract has open claim(s) and deduct claims in cancellation rule.
Error	CancelClaimDate	Cancellation date must be on or after last reported claim date ( {0} ).
Error	SAVE_CONTRACT_TO_BE_PAID_FAIL	Save to contract to be paid failed.
Error	CONTRACT_CANCEL_FAIL	Save cancel payee failed.Cannot Cancel Contract.
Error	CAN_023	Contract could not be cancelled due to a missing configuration of cancellation defaults.
Error	CAN_024	Cancel Refund Payee Type is invalid. Valid Values: 1. (Seller) 2. (Customer) 3. (Lienholder) 4. (Customer And Lienholder) 5. (Lienholder And Customer) 6. (Agent)
Error	CAN_025	Cancel Refund Payee Type is not valid for this contract.
Error	CAN_026	Cancel Calc Basis is required when Cancel Refund Payee Type is provided.
Error	CAN_027	Cancellation Calc Basis is invalid. Valid Values: N - Net R - Retail
Error	CAN_028	Cancel Calc Basis is not valid for CancelCalcPayee Type. When CancelCalcPayeeType is Seller, cancellation calc method of ‘R’ (‘Retail’) is not permitted.
Error	CAN_29	User does not have permission to override Cancel Calc Basis.

Save Contract Error Messages

Message Type	Error code	Message Text
Error	rfvTPACode	TPA Code is required.
Error	rfvDealerNumber	Seller Number is required.
Error	rfvContractNumber	Contract Number is required.
Error	BILLDATE_RATE	The pending billed contract cannot be saved without rates.
Error	SALEDATE_EXCEED_MIN	Sale Date cannot be less than {0}.
Error	SALEDATE_EXCEED	Sale Date exceeds future Sale Date limit.
Error	rfvSaleDate	Sale Date is required.
Error	EFFDATE_GT_EXPDATE	Effective Date cannot be greater than or equal to Expiration Date.
Error	EFFODOM_GT_EXPODOM	Effective Odometer is greater than the Expiration Odometer based on plan eligibility rules. Contract cannot be saved.
Error	INSVDTGTSLDT	In Service Date cannot be greater than sale date.
Error	INSERVICE_GT_DATE	In Service Date cannot be greater than {0}.
Error	INSERVICE_LT_YEAR	In Service Date cannot be less than year {0}.
Error	rfvInServiceDate	In Service Date is required.
Error	VPDTGTSLDT	Vehicle Purchase Date cannot be greater than sale date.
Error	VPDTGTTODAY	Vehicle Purchase Date cannot be greater than {0}.
Error	rfvVehiclePurchaseDate	Vehicle Purchase Date is required.
Error	rfvTemplate	{0} is required. This error is returned if the Additional Contract field value is required.
Error	AdditionalInfoLength	Invalid {0}. {0} must be {1} characters. This error is returned if the Additional Contract field value does not meet the length requirement.
Error	AdditionalInfoUnique	Value entered for {0} is not unique. Please enter a different value. This error is returned if the Additional Contract field value is not unique.
Error	EXPDATE_LT_SALEDATE	Expiration date {0} cannot be earlier than the sale date {1}.
Error	SALEODOM_LT_EXPODOM	Sale Odometer must be less than Expiration Odometer.
Error	VEHICLE_CLASS_NOT_FOUND	Vehicle Class is not found.
Error	DEALER_NOT_ACTIVE_SALEDATE	The seller account is not active for this sale date.
Error	DEALER_SALE_AUTHORITY	The seller has no sale authority for this period.
Error	rfvProgram	Program is required.
Error	PROGRAM_INVALID	Program is Invalid.
Error	rfvPlan	Plan is required.
Error	PLAN_INVALID	Plan is invalid.
Error	rfvTerm	Term is required.
Error	TERM_INVALID	Term is invalid.
Error	rfvDeduct	Deductible is required.
Error	DEDUCT_INVALID	The deductible is invalid.
Error	PAYMENT_OPTION_REQUIRED	Payment Option Required.
Error	rfvCustLastName	Customer Last Name is required.
Error	rfvCustAddress	Customer Address is required.
Error	rfvCustCity	Customer City is required.
Error	rfvCustState	Customer State is required.
Error	rfvCustZipCode	Customer Zip Code is required.
Error	EMAILVALID	Email not in correct format.
Error	revZipCode	Invalid Zip/Postal Code.
Error	PHONEINVALID	Invalid Phone number.
Error	rfvDealType	Deal Type is required.
Error	INVALID_FIRST_PAYMENT_DATE	First Payment Date must be greater than or equal to Sale Date.
Error	rfvInsCarrier	Insurance Carrier is required.
Error	ZERONETRATE	Contract cost must be greater than $0.00 to be billed or activated.
Error	GETRATES0001	The contract is not eligible because the Financed Amount is greater than {0:P3} of the Vehicle Sale Price.
Error	GETRATES0002	The contract is not eligible because the Vehicle Sale Price is greater than the Maximum Vehicle Sale Price.
Error	GETRATES0003	Financed Amount is greater than {0:P3} of the MSRP.
Error	GETRATES0004	MSRP exceeds Maximum MSRP limit of {0}.
Error	GETRATES0017	APR is less than Minimum APR limit of {0:P3}.
Error	GETRATES0005	APR exceeds Maximum APR limit of {0:P3}.
Error	GETRATES0006	Financed Amount is less than Minimum Financed Amount of {0:c}.
Error	GETRATES0014	Financed Amount is greater than Maximum Financed Amount of {0:c}.
Error	GETRATES0008	APR is required.
Error	GETRATES0009	Finance Term is required.
Error	GETRATES0013	MSRP is required.
Error	GETRATES0018	The term {0} months is not available for this plan.
Error	VIN_NOT_ENTER	VIN is not entered.
Error	VIN_INVALID	Invalid VIN.
Error	VHL_ELIG_COV	This vehicle is not eligible for coverage (Eligibility For Manufacturer's Warranty).
Error	EXT_ELIG_REQ_APPRV	This extended eligibility requires approval.
Error	SALEODOM_EXCEED_MILE	The sale odometer exceeds the odometer eligibility mileage.
Error	SALEDATE_INSERVICEDATE_SAME	Sale date and in service date are the same and the sale odometer is over {0} miles.
Error	rfvFinanceAmount	Financed Amount is required.
Error	RTLRL035	You do not have permissions to activate or bill a contract with a Retail Rate that differs from the Regulated Retail.
Error	RTLRL036	You do not have permissions to activate or bill a contract with a Retail Rate that differs from allowable Markup.
Error	FIMgrReqOnContract	Please select F&I Manager, it is required to issue a commission payment.
Error	MENU_DISABLED	Menu not enabled for eContracting.
Error	DLRNOTEXIST	Dealer does not exist.
Error	AGTNOTEXIST	Agent does not exist on the contract record."
Error	LINNOTEXIST	Lien Holder does not exist.
Error	CycleMonthInvalid2	Cycle month is not defined in SCS cycle months.
Error	SAVEFAIL	Cannot save record.