AutoBill.migrate
Web Session Object
Transaction Object
Token Object
Season Set Object
Refund Object
RatePlan Object
Product Object
Payment Provider Object
Payment Method Object
NameValuePair Object
GiftCard Object
Entitlement Object
Chargeback Object
Campaign Object
BillingPlan Object
AutoBill Object
Address Object
Activity Object
Account Object
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:
|
400 (Transaction migration error messages) |
|
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
}
For Users
Learn More