Skip to main content
Vindicia Knowledge Center

AutoBill.update

AutoBill.update

AutoBill.update

The 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, CashBox authorizes the full amount immediately. In the event of a failure, CashBox responds according to the immediateAuthFailurePolicy, whose options include the following:

  • doNotSaveAutoBill—(default) deletes the AutoBill without saving it.
  • putAutoBillInRetryCycle—creates the AutoBill and retries the authorizaton.
  • putAutoBillInRetryCycleIfPaymentMethodIsValid—(recommended)

If billing is scheduled for a future date, the validateForFuturePayment flag is used to determine whether to do a minimal authorization ($0/$1) immediately. To request an immediate validation for a new or existing AutoBill when billing is not scheduled for "today", set the validateForFuturePayment flag to 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, CashBox 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 CashBox 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 this 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; CashBox automatically generates the VID when you call update(). When updating an existing AutoBill object, identify it with its VID or your AutoBill ID (merchantAutoBillId).

Products may have an array of Products beneath them (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.addProduct.

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 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 to create or update. Identity this object with its VID or merchantAutoBillId.

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 CashBox to bill on the service period start date (the default).
  • billingRule: an enumerated string value (Advance or Arrears), informing CashBox in which direction from the scheduled billing date to select the specified billing date. If no specified_billing_day is provided, this parameter is ignored.

You can also use these parameters to change the billing date at migration of an AutoBill object. For more information, see Advance and Arrears Billing Option for AutoBills in the CashBox Programming Guide.

ImmediateAuthFailurePolicy: if the billing is scheduled for "today", CashBox authorizes the full amount immediately. In the event of a failure of the initial transaction for the AutoBill, CashBox responds according to the immediateAuthFailurePolicy, whose options include the following:

  • 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 CashBox continuously retries the credit card number.
  • putAutoBillInRetryCycleIfPaymentMethodIsValid—(recommended.) Creates the AutoBill and retries the credit card only if CashBox has evidence that the authorization will succeed.

validateForFuturePayment: if billing is scheduled for a future date, this flag is used to determine whether to do a minimal authorization ($0/$1) immediately.

minChargebackProbability: a number between 0 and 100 by which you specify your fraud risk tolerance level. A chargeback probability (also called the risk-screening score or risk score) of 100 indicates that CashBox is 100% certain that a transaction is fraudulent and will result in a chargeback. Specify your acceptable threshold for chargeback probability with this parameter. If the score evaluates to more than your tolerance level, the update call will fail.

If you do not set minChargebackProbability, CashBox defaults to 100, meaning that all transactions are acceptable and that no risk screening occurs. For more information on CashBox risk-screening, see ChargeGuard in the CashBox Programming Guide. 

ignoreAvsPolicy: a Boolean flag which, when set to true, causes CashBox to override the AVS policy and update the paymentMethod, regardless of the AVS return code. If set to false or null, (and if validatePaymentMethod 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 CashBox to override the CVN policy and update the paymentMethod, regardless of the CVN return code. If set to false or null, (and if validatePaymentMethod is 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 / CVN Policy Evaluation Results are mapped to the AutoBill and Entitlement creation as follows:

Policy Evaluation

Result

Success

AutoBill is active and entitlement is granted.

Pending

AutoBill is pending and entitlement is granted.

Fail

AutoBill is canceled and entitlement is inactive.

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 CashBox 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 AutoBill did 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 CashBox cancel reason codes, or define additional codes using the CashBox Portal or the API. (See "Canceling AutoBills with Reason Codes" in the CashBox Programmer’s Guide.) Supplying an undefined cancel reason code may result in an error.

Returns

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

Return Code

Return String

400

One of the following:

  • Can not use this reason code: $reasonCode if its reserved for Vindicia use only.

  • Unable to load cancel reason code.

 

Output

return: an object of type Return 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 CashBox database, this method creates a new AutoBill object. Otherwise, CashBox 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.

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.

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 CashBox 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.

Returns

In addition to those listed in Table 1: Standard Return Codes, this call returns:

Return Code

Return String

400

One of the following:

  • Failed to translate credit error-description.
  • Unable to create AutoBill: error-description.
  • Data validation error: Failed to create Payment-Type-Specific Payment Record: Credit Card conversion failed: Credit Card failed Luhn check.
  • Unable to create autobill: Must specify product to create autobill with!
  • Campaign code XYZ is not usable: Code XYZ is not valid.
  • No eligible, undiscounted items found for campaign code.

402

Unable to create AutoBill: error-description.

(This return code means that validation failed.)

403

Cannot update an AutoBill that has completed the retry cycle, and is past its endTimestamp.

407

AVS policy evaluation failed.

408

CVN policy evaluation failed.

409

AVS and CVN policy evaluations failed.

410

AVS and CVN policy evaluations could not be performed.

Example

// To create a subscription, to an existing product, for an
// existing customer, using an existing billing plan

$autobill = new AutoBill();
$account = new Account();
$product = new Product();
$billPlan = new BillingPlan();

// Identify a previously created product by your unique ID

$product->setMerchantProductId('12345');

// Identify a previously created billing plan by your unique ID

$billPlan->setMerchantBillingPlanId('bp12345');

// Identify a previously created account by your unique ID
// Assumption: Account already has a payment method attached to it
// which will be used by the AutoBill automatically

$account->setMerchantAccountId('acct12345');

$autobill->setAccount($account);

// AutoBills may have multiple products
// each in an AutoBillItem as an array:

$item = new AutoBillItem();
$item->setIndex(0);

// set the Product in the AutoBillItem

$item->setProduct($product);

// set the Product (AutoBillItem)

$response = $autobill->setItems(array($item));

$autobill->setBillingPlan($billPlan);
$autobill->setMerchantAutoBillId('ab-44822'); // your ID for the AutoBill
$autobill->setCurrency('USD');

$validate = true;
$fraudScore = 100 ; // do not want to do risk screening

$response = $autobill->update('putAutoBillInRetryCycleIfPaymentMethodIsValid',

$validate, $fraudScore, true, true);

if($response['returnCode'] == 200 && $response['created'] ) {

print "AutoBill created with VID "

. $response['data']->autobill->getVID() . "\n";

if ( $response['authStatus'] != null ) {

$txnStatus = $response['authStatus'];
log (" CVN return code: "

. $txnStatus->getCreditCardStatus()->getCvnCode()
. "AVS return code"
. $txnStatus->getCreditCardStatus()->getAvsCode() . "\n");

}

}

For Users

Learn More
For Users

Cashbox Features

Learn More
Cashbox Features
Back to Top