update method is used to create a new AutoBill object. An AutoBill object represents a customer subscription with recurring billing. Be sure to properly construct the AutoBill (see AutoBill Data Members) before passing it into this call.
Call this method to first risk-screen the related Payment Method for the AutoBill object. Enabling risk screening causes this method to score a Transaction for the related Payment Method. (See the Transaction.score method.) If the score is below the threshold specified in the minChargebackProbability parameter, the AutoBill object will be created. If the score is equal to or greater than the threshold, the object will not be created. For scoring to succeed, you must specify, in the AutoBill object, the source IP address from which the customer requested this subscription, and, in the associated payment method, the billing address.
If the billing is scheduled for today, Subscribe authorizes the full amount immediately. In the event of a failure, Subscribe responds according to the immediateAuthFailurePolicy, whose options include the following:
doNotSaveAutoBill—(default) deletes the AutoBill without saving itputAutoBillInRetryCycle—creates AutoBill and retriesthe authorizatonputAutoBillInRetryCycleIfPaymentMethodIsValid—(recommended)
true. An immediate minimal authorization will be performed. This flag is ignored when creating a new AutoBill with an immediate billing (scheduled for today) in favor of the full amount authorization.
By default, if a new AutoBill creation or modification requires billing within 25-hours, Subscribe does an immediate billing with full authorization. The purpose of this behavior is to minimize processing fees by combining the validation transaction with the billing transaction. This behavior has the added benefit of enabling you to respond to payment failures in real time—that is, while the customer is on line.
If, however, you offer a one-day initial billing cycle, or if you require that the initial transaction date be tomorrow rather than today, use the DelayFullAuthToInitialBillingDate option to prevent immediate billing when an AutoBill is created. This causes Subscribe to initiate a validation transaction today, and a billing transaction tomorrow (the specified start date of AutoBill/subscription). This option is false by default. See initialAuth below.
You can also use the AutoBill.update() method to specify a regular billing in advance of, or after, the Service Period start date. You can allow the service dates to be maintained according to the billing plan, while billing for those periods on specified days of the month, before or after the scheduled service date, using the specifiedBillingDay and billingRule parameters.
To create an AutoBill object, initialize the object and set the values for its data members as appropriate, then call the update() method to create the object on the Vindicia server. When creating a new AutoBill object, do not set a value for VID; Subscribe automatically generates the VID when you call update(). When updating an existing AutoBill object, identify it with its VID or your AutoBill ID (merchantAutoBillId).
A Product can have an array of products beneath it (sub-products). When a sub-product is placed on an AutoBill, all attributes of the top-level product will apply to the AutoBill, except for entitlements, which will be the union of the entitlements of all of the products and sub-products.
Note: The AutoBill.update method can not be used to add Products to an AutoBill. To add Products, use AutoBill.modify.
To apply a Campaign discount to an AutoBill, the Billing Plan must have prices defined in a currency that matches the currency set on the AutoBill. If the Billing Plan price is defined in currencies different from those used for the AutoBill, the discount will not be applied.
Note: The customer’s Account must exist before any Hosted Page related call references that Account.
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 amethod 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 to create or update. Identify this object with its VID or .
To specify a regular billing in advance of, or after, the regularly scheduled Service Period start date, use the following parameters:
- specifiedBillingDay: an integer (1-31) specifying the day of the month on which to bill (values 29-31 automatically work as the last day of the month for calendar months that do not have 29, 30, or 31 days). Providing no value or null in this parameter instructs Subscribe to bill on the service period start date (the default).
- billingRule: an enumerated string value (
AdvanceorArrears), informing Subscribe in which direction from the scheduled billing date to select the specified billing date. If nospecified_billing_dayis provided, this parameter is ignored.
- doNotSaveAutoBill—(default) deletes the AutoBill. Select this setting if you want to start over, ask the consumer for a new credit card number, and create a new AutoBill.
- putAutoBillInRetryCycle—creates the AutoBill and places it in a “retry” cycle, in which Subscribe continuously retries the credit card number
- putAutoBillInRetryCycleIfPaymentMethodIsValid—(recommended.) Creates the AutoBill and retries the credit card only if Subscribe has evidence that the authorization will succeed
update call will fail.
If you do not set minChargebackProbability, Subscribe defaults to 100, meaning that all transactions are acceptable and that no risk screening occurs. For more information on Subscribe risk-screening, see Common ChargeGuard Programming Tasks in the Subscribe Programming Guide.
ignoreAvsPolicy: a Boolean flag which, when set to true, causes Subscribe to override the AVS policy and update the paymentMethod, regardless of the AVS return code. If set to false or null, (and if validateForFuturePayment is set to true) the AVS return code will be used to determine whether to update the paymentMethod.
ignoreCvnPolicy: an optional Boolean flag which, when set to true, causes Subscribe to override the CVN policy and update the paymentMethod, regardless of the CVN return code. If set to false or null, (and if validateForFuturePaymentis set to true) the CVN return code will be used to determine whether to update the paymentMethod.
If both ignoreAvsPolicy and ignoreCvnPolicy are true, no policy evaluation will be done. If only one of the flags is set to true, policy evaluation will not be considered for that element (AVS or CVN). If no value is passed in for either parameter, they will default to false, and the AVS and CVN policy evaluations will be used to determine PaymentMethod validation status.
Note:
The AutoBill will not be saved if validation is requested and fails.
The AVS and CVN Policy Evaluation policy Results are mapped to the AutoBill and Entitlement creation as follows:
For more detail on AVS and CVN Return Codes, please work with your Vindicia Client Services representative.
campaignCode: an optional Coupon or Promotion code, used in conjunction with a Campaign, to obtain a discount on this AutoBill.
dryrun: a Boolean flag that, if set to
true, will return the updated AutoBill, without recording the result in the Subscribe database. Use this method to compute the cost of an AutoBill without committing to the change. (The projected billing amount will be returned in the Transaction object of the nextBilling data member of the returned AutoBill object.)
If the AutoBilldid not exist before, it will not exist afterward; if it did exist before, it will not change. (No payment method validations, authorizations or charges will be performed if dryrun is true).
Note: Do not change the established currency type.
cancelReason: (Optional) reason for canceling the AutoBill. You can use predefined Subscribe cancel reason codes, or define additional codes using the Subscribe Portal or the API. (See Canceling AutoBills with Reason Codes in the Subscribe Programming Guide.) Supplying an undefined cancel reason code may result in an error.
initialAuth: (Optional) An enumerated value that specifies how to manage authorization and capture when the scheduled initial billing is within 25 hours. Default behavior is equivalent to AuthImminentBilling:
AuthImminentBilling: By default, charges to be billed within 25 hours are authorized and captured immediately to save on processing fees. The immediate full amount authorization provides the validation.Returns.DelayFullAuthToInitialBillingDate: This value forces the specified validation behavior now, delaying the full authorization and capture attempt until the specified AutoBill Start Date.
Note: This feature is supported only for the Barclaycard Smartpay Gateway.
unknownStart: (Optional) a Boolean flag that, when set to
True, will create an AutoBill with no start date and status Pending Activation. An AutoBill created with an unknown start date must be activated with an AutoBill.Activate() call. Otherwise the AutoBill will persist in the pending activation state for up to two years from the creation date, and then be automatically canceled.
The unknown start functionality is currently supported only for credit card and debit card payment methods, and for season based entitlements. See the AutoBill.activate method for the AutoBill object.
fullAuthDelayedCapture: If true and the AutoBill has a future start date or a free trial period, the AutoBill will be created with an auth for the full amount of the first paid-for period.
enable3ds: Disable 3DS authentication flow for this transaction if false; if true or undefined, the 3DS authentication flow will be determined by the merchant option flag use3ds.
Output
return: an object of typeReturn that indicates the success or failure of the call.
autobill: the AutoBill object that was created or updated. If you specify a VID or your AutoBill ID for autobill, but that ID does not exist in the Subscribe database, this method creates a new AutoBill object. Otherwise, Subscribe updates the AutoBill object whose ID matches the input.
created: a Boolean flag that, if set to true, indicates that this method has created a new AutoBill object. A false setting indicates that update or upgrade has updated an existing AutoBill object.
authStatus: contains the response from the payment processor (either the initialTransaction auth response or that of the validation response). For example, the Address Verification Service (AVS) and Card Verification Number (CVN) response codes.
For some payment methods that do not support immediate payment (MerchantAcceptedPayment/invoicing), the Transaction is still included to provide the relevant Transaction and item details, including taxes and discounts, to support display in quotes (using dryrun) or confirmation pages.
score: the risk score for the payment method used for the AutoBill if you enabled risk scoring by specifying the value of the input parameter minChargebackProbability to be less than 100.
Normally, this value is between 0 and 100, where 100 is the highest risk score, indicating maximum chargeback probability. A value of -1 indicates that Subscribe could not evaluate the score because of missing data such as an IP address or a full billing address. A value of -2 indicates an error condition.
scoreCodes: an array of ScoreCode objects, each of which includes a code and corresponding message explaining why the risk score evaluated to a certain value.
initialTransaction: The initial transaction for new AutoBills. Creates an initial transaction for immediate billing, even if the amount is zero. Outputs a transaction object that contains complete information about the transaction, including the date, amount, and currency of the first billing.
strongCustomerAuthentications: Further instructions to client to authorize a Transaction that was subjected to SCA.

