AutoBill.migrate

The migrate method enables you to import existing subscription and transaction information from your current billing system to CashBox. This call creates new AutoBills that reflect the imported information.

You can call AutoBill.migrate multiple times for a given AutoBill. With the first call, CashBox creates the AutoBill, and build the billing schedule records that correspond to any MigrationTransactions that are included in the call.

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.

When you call AutoBill.migrate on an existing AutoBill—that is, when you specify a VID or merchantAutoBillId of an AutoBill that already exists—CashBox backfills the existing AutoBill's Transaction history, (importing older Transactions for the subscription), and makes no attempt to update the AutoBill itself.

Note While you can create new Accounts and PaymentMethods with this call, you cannot create new Products or BillingPlans. Be certain that any Products or BillingPlans referenced by an inputMigrationTransaction object are created before making the call.

AutoBill.migrate supports the following payment processors:

• Chase Paymentech
• Merchant e-Solutions
• Litle & Co.
• PayPal

AutoBill.migrate supports the following payment methods:

• Credit Card
• PayPal
• Merchant accepted payment (MAP) method—Pay By Invoice

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

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 nospecified_billing_day is provided, this parameter is ignored.

You can use these parameters to change the billing date at migration (or creation) of an AutoBill object, or specify them later using AutoBill.update. For more information, see Advance and Arrears Billing Option for AutoBills in the CashBox Programming Guide.

Note For this call, the following AutoBill data members are required:

• account
• billingPlan
• currency
• items
• paymentMethod (For this call, this field must be CreditCard or MAP)
• startTimestamp

nextPeriodStartDate: the next scheduled billing date for this AutoBill. If not provided, it will be assumed that this AutoBill is terminal and no future billings are to be scheduled. (For the first AutoBill.migrate call for a given AutoBill, this field is required.)

When migrating a subscription with a Merchant Accepted Payment (MAP), specifying a nextPeriodStartDate will alter the invoice/billing schedule. If this parameter is not set, CashBox will create all invoices from the last transaction provided to “now” and schedule the next (an invoice in OPEN status) according to the billing plan provided.

migrationTransactions: an array of MigrationTransaction objects which define the history of this AutoBill. 

When migrating Transactions with a MAP, a Transaction for this AutoBill must be included in the initial AutoBill.migrate call; and the latest status record must show that the Transaction is either Captured, Canceled, Refunded, Settled, or Void. No other TransactionStatus values can be used for this call.

Also for MAP, we strongly recommend that you provide at least the last invoice transaction. Regardless of how many transactions you include, CashBox will create invoices for all periods between the “last transaction” and “now”. If you provide no transactions, CashBox will create an invoice for every period since the indicated start date of the subscription. Unless a successful Transaction is provided, CashBox will assume an invoice period is unpaid (DUE or OVERDUE).

CashBox will not create invoices for periods prior to the last provided transaction unless covered by another migrated transaction—unspecified periods will be assumed to have been PAID in full.

Note Any Transactions migrated to CashBox will follow your defined retry sequence. For example, an AutoBill migrated to CashBox with a single Transaction with status Cancelled will trigger a retry.

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.

Output

return: an object of type Return that indicates the success or failure of the call.

autobill: the AutoBill object that was created through migration. If you specify a VID or merchantAutoBillId for autobill, and that ID does not yet exist in the CashBox database, this method will create a new AutoBill object. If the ID does exist, CashBox will update the corresponding AutoBill object.

Returns

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

Return Code	Return String
400	One of the following: At least one migrationTransaction must be included in AutoBill.migrate request. Error validating parameters for AutoBill Migration. Migrated AutoBills must have at least one item. Product must be pre-defined for AutoBillItem autoBillItem. Product not defined for AutoBillItem autoBillItem. Invalid AutoBillItem addedDate date. Invalid AutoBillItem removedDate: date. BillingPlan must be pre-defined. BillingPlan with identifier identifier not found. Campaign code campaignCode is not valid. Invalid value for transitionedFromMerchantAutoBillItemId: autoBillItemId. Invalid value for transitionedToMerchantAutoBillItemId: autoBillItemId. Invalid value for nextPeriodStartDate. Transaction Migration attempt failed: error. (See the Transaction.migrate error list for details that could be appended to this message.) Migration Transactions not specified. PaymentMethod not specified. Unsupported Payment Type: type. TransactionBilling migration details not provided for initialization of AutoBill. No BillingPlan: Cannot determine TransactionBillingSequence details. Billing Plan on last Transaction submitted does not match AutoBill BillingPlan. AutoBillCycle (transaction_billing_sequence) not defined. Unable to determine current AutoBill BillingPlanPeriod. Unable to determine Billing Period billing sequence.Failed to determine BillingPlanPeriod index for AutoBill Migration. BillingPlanCycle cannot be greater than autoBillCycle (transaction_billing_sequence). Currency code not defined in row n of Transaction Array for AutoBill Migration. Transaction currency (currency) does not match AutoBill currency (currency). Transaction for retry # n in billing sequence m already exists. Transaction migration failed for Transaction # n during Migration of AutoBill autoBill. (See the Transaction.migrate error list for details that could be appended to this message.) Mismatch found between AutoBill billing sequence (n), and the max TransactionBilling sequence (m). Transactions cannot be associated with an AutoBill's final TransactionBilling. TransactionBilling for sequence sequence is in invalid state (state) for AutoBill migration. (TransactionBillings generated by the migrate process should be in one of the following states: Success, Free, or Deferred.) Original activity date for historical TransactionBilling sequence n is in the future (date). billing date for TransactionBilling (date) is greater than latest allowed (date). Transaction (index) in sequence sequence is in an invalid state (state) for AutoBill migration. (The Transaction state (which is derived from the disposition log) must be one of the following: Captured, Cancelled, Refunded, Settled, or Void.) NRC Transaction in sequence $sequence is in an invalid state (state) for AutoBill migration. (Non-Recurring-Charge Transactions must be in one of the states specified for Recurring Transactions (above).) Transaction autoBillCycle not defined. billingPlanCycle not defined. billingPeriodStart not defined. Failed to map AutoBill Items to Transaction Items during Transaction Migration. Cannot map Transaction Items to AutoBill Items - No Transaction Items! Cannot map Transaction Items to AutoBill Items - No AutoBill Items! Failed to determine Product SKU for AutoBill Item index n while attempting to map Transaction Items to AutoBill Items. Failed to map AutoBillItem ID autoBillItemId, to a TransactionItem. Unable to determine AutoBill BillingPlanPeriod for Transaction ident transactionId. Unable to determine Billing Period billing sequence for Transaction ident transactionId. Failed to determine BillingPlanPeriod index associated with Transaction ident transactionId.
400 (Transaction migration error messages)	MigrationTransaction not provided. Invalid paymentProcessor: paymentProcessor. MigrationTransaction must include at least one statusLog record. Failed to convert salesTaxAddress. Attempt to migrate Transaction which already exists. Unsupported Payment Type: paymentType. Failed to prepare auth_response for Migrated Transactions. Unable to determine currency for migrated Transaction. Calculated Transaction amount (XXX.XX) does not match input amount (YYY.YY) on migrated Transaction.

Example

//To migrate an AutoBill for a pre-existing BillingPlan,
//Product, Account, and PaymentMethod.
//Note that it is possible to define new Account and
//PaymentMethod objects within AutoBill.migrate.
//The Product(s) and BillingPlan must, however, be pre-defined.

$billplanVid = 'c6743226ea41afd9db71c0c612a870bfcaa68fa7';
$productVid = '124a5540e359d59ba2a301a4b86cd5434f5c99d3';
$accountVid = '3915038987280cc31b103dbdf291cfd68181b385';
$paymentmethodVid = '822690237671dbb37014bb4c5262e0067ab94f97';
$addressVid = '3c14d744baa5cd618c1e0ff2c1f54b408e8c65e9';

$billPlan = new BillingPlan();
$product = new Product();
$account = new Account();
$autobill = new AutoBill();
$paymentMethod = new PaymentMethod();
$address = new Address();

$billPlan->setVid($billplanVid);
$product->setVid($productVid);
$account->setVid($accountVid);
$paymentMethod->setVid($paymentmethodVid);
$address->setVid($addressVid);

//Define the AutoBill to be Migrated

$item = new AutoBillItem();
$item->setIndex(0);
$item->setAddedDate('2014-01-06T10:14:14-08:00');
$item->setMerchantAutoBillItemId('merchantAutoBillItem1391710456');
$item->setProduct($product);

$autobill->setaccount($account);
$autobill->setItems(array($item));
$autobill->setBillingPlan($billPlan);
$autobill->currency('USD');
$autobill->setCustomerAutoBillName('MGRT_1391710573_cabn_1391710456');
$autobill->setMerchantAutoBillId('MGRT_1391710573_valg_1391710456');
$autobill->setPaymentMethod($paymentMethod);
$autobill->setStartTimestamp('2014-01-06T10:14:14-08:00');

//Next, define the MigrationTransaction to be included
//in the AutoBill.migrate call

$taxItemA = new MigrationTaxItem();
$taxItemA->setAmount(.92);
$taxItemA->setJurisdiction('COUNTY_19');
$taxItemA->setName('SALES TAX');

$taxItemB = new MigrationTaxItem();
$taxItemB->setAmount(6.67);
$taxItemB->setJurisdiction('DISTRICT');
$taxItemB->setName('CA DISTRICT SALES TAX');

$txItemA = new MigrationTransactionItem();
$txItemA->setItemType('RecurringCharge');
$txItemA->setMigrationTaxItems(array($taxItemA, $taxItemB));
$txItemA->setName('product 1391710450 default plan');
$txItemA->setPrice(49.99);
$txItemA->setServicePeriodStartDate('2014-01-06T00:00:00');
$txItemA->setServicePeriodEndDate('2014-03-05T00:00:00');
$txItemA->setSku('bp_1391710450');
$txItemA->setTaxClassification('DC010500');

// This should be the Avalara tax code associated with this product

$txItemB = new MigrationTransactionItem();
$txItemB->setItemType('RecurringCharge');
$txItemB->setMerchantAutoBillItemId('merchantAutoBillItem1391710456');
$txItemB->setName('product_1391710450_1');
$txItemB->setPrice(42.00);
$txItemB->setServicePeriodStartDate('2014-01-06T00:00:00');
$txItemB->servicePeriodEndDate('2014-03-05T00:00:00');
$txItemB->setSku('1391710450_1');
$txItemB->setTaxClassification('DC010500');

// This should be the Avalara tax code associated with this product

$creditCardStatusA = new TransactionStatusCreditCard();
$creditCardStatusA->setAuthCode('000');
$statusLogA = new TransactionStatus();
$statusLogA->setCreditCardStatus($creditCardStatusA);
$statusLogA->setPaymentMethodType('CreditCard');
$statulLogA->setStatus('Captured')
$statusLogA->setTimestamp('2014-02-06T10:16:06-08:00');

$creditCardStatusB = new TransactionStatusCreditCard();
$creditCardStatusB->setAuthCode('000');
$statusLogB = new TransactionStatus();
$statusLogB->setCreditCardStatus($creditCardStatusB);
$statusLogB->setPaymentMethodType('CreditCard');
$statusLogB->setStatus('New');
$statusLogB->setTimestamp('2014-02-06T10:14:51-08:00');

$migrationTransaction = new MigrationTransaction();
$migrationTransaction->setAccount($account);
$migrationTransaction->setAmount(99.58);
$migrationTransaction->setAutoBillCycle(0);
$migrationTransaction->setBillingDate('2014-01-06T00:00:00');
$migrationTransaction->setBillingPlanCycle(0);
$migrationTransaction->setCurrency('USD');
$migrationTransaction->setDivisionNumber('iAmTheWalrus');
$migrationTransaction->setMerchantBillingPlanId('bp_1391710450');
$migrationTransaction->setMigrationTransactionItems

(array($txItemA, $txItemB));

$migrationTransaction->setPaymentMethod($paymentMethod);
$migrationTransaction->setPaymentProcessor('Litle');
$migrationTransaction->setPaymentProcessorTransactionId('1069115');
$migrationTransaction->setRetryNumber(0);
$migrationTransaction->setSalesTaxAddress($address);
$migrationTransaction->setShippingAddress($address);
$migrationTransaction->setStatusLog(array($statusLogA, $statusLogB));
$migrationTransaction->setType(Recurring);

//Migrate AutoBill into CashBox

$response = $autobill->migrate('2014-03-06T00:00:00', array($migrationTransaction));
if($response['returnCode'] == 200)
{

//AutoBill and Transaction(s) migrated successfully

print "AutoBill migrated with VID " .
$response['data']->autobill->getVID() . "\n";

}

else

{

//AutoBill migration failed

}