Skip to main content
Vindicia Knowledge Center

Transaction.migrate

Transaction.migrate

Transaction.migrate

The migrate method allows you to enter Transactions processed outside of CashBox into the CashBox database. Transactions imported to CashBox using this method are stored in the database. Those that are entered with a status of failed will be processed by CashBox according to your defined retry schedule.

Transactions entered using this method may be searched and analyzed, both through the CashBox UI, and using the Transaction.fetchDeltaSince method.

After migration, these Transactions will be processed and treated as if they originated with CashBox, allowing you to use this method to import historic billing information for your customers.

When you call this method to import a batch of Transactions, Vindicia queues the data, and then processes it in the order received, before adding it to the database. Lag time exists between the time you migrate a transaction, and the time it appears in the CashBox database and UI. The lag varies according to your transaction volume, and that of other merchants currently in the queue.

Vindicia recommends small batches for this call. If your migrated Transaction volume is high, call Transaction.migrate more often to reduce the amount of data sent in one call. (The optimal batch size depends on the total amount of data being sent.) To minimize timeouts, consider adjusting the timeout setting in the client library and the batch size for the call.

Transaction.migrate supports the following payment processors:

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

Transaction.migrate supports the following payment methods:

  • Credit Card
  • PayPal

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.

migrationTransactions: an array of migrationTransaction objects to import to CashBox.

Note While this method uses the same migrationTransaction subobject as the AutoBill.migrate method, the two methods require that different data members be populated. 

Do not populate the following migrationTransaction data members for the Transaction.migrate call:

  • autoBillCycle
  • billingPlanCycle
  • merchantBillingPlanId

Do not populate the following migrationTransactionItem data member for the Transaction.migrate call:

  • merchantAutoBillItemId

Output

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

response: an array of TransactionValidationResponse objects.

Returns

When you migrate a batch of Transactions, a return code of 200 means that CashBox has received your data and queued it for processing. During this process, if CashBox discovers problems with the data that prevent it from being added to the CashBox database, CashBox attempts to correct the data. If the attempt fails, CashBox will ask you to correct the errors and might request that you report the data again.

The Return object also contains an attribute called soapId. For the migrate call to succeed, you must log the value of soapId. If, for some reason, the migrated Transactions do not make it into the CashBox database, provide the soapId value to CashBox to facilitate tracking of your batch in the CashBox system.

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

Return Code

Return String

 

400

One of the following:

  • Unable to save transactions: error-description.
    This code is returned if an error occurs in the processing of a transaction and it is the only transaction in the batch.
  • One or more Transaction migrations failed.
  • Error descriptions provided in TransactionValidationResponse (contained in the response array of the return).
  • Invalid field(s) for non-recurring Transaction Migration: (invalid fields)
    • Invalid MigrationTransaction fields(when calling Transaction.migrate): autoBillCycle, merchantBillingPlanId, billingPlanCycle, billingDate, retryNumber.
    • Invalid MigrationTransactionItem fields (when calling Transaction.migrate): servicePeriodStartDate, servicePeriodEndDate, merchantAutoBillItemId.
  • Unable to prepare transaction for migration: error.
    (Details provided in common AutoBill.migrate/Transaction.migrate 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 a Transaction that has been processed via an external system
//Create the customer account objects

my $address = new Address();
$address->setAddr1('11235 Fibonacci St.');
$address->setCity('San Mateo');
$address->setCountry('US');
$address->setDistrict('CA');
$address->setName('Forest Chump');
$address->setPhone('(650) 555-1212x42');
$address->setPostalCode('94403');

my $creditCard = new CreditCard();
$creditCard->setAccount('4222261111112664');
$creditCard->setBin('22226');
$creditCard->setAccountLength(16);
$creditCard->setExpirationDate('201602');
$creditCard->setLastDigits

my $paymentMethod = new PaymentMethod();
$paymentMethod->setAccountHolderName('Forest Chump');
$paymentMethod->setActive(1);
$paymentMethod->setBillingAddress($address);
$paymentMethod->setCreditCard($creditCard);
$paymentMethod->setCustomerSpecifiedType('VI');
$paymentMethod->setMerchantPaymentMethodId('vi_1391721679');
$paymentMethod->setSortOrder(0);
$paymentMethod->setType('CreditCard');

my $account = new Account();
$account->setEmailAddress('devnull@devnull.com');
$account->setEmailTypePreference('html');
$account->setMerchantAccountId('maccid_1391721679');
$account->setName('Forest Chump');
$account->setPaymentMethods(array($paymentMethod));
$account->setShippingAddress($address);

//Create the Transaction objects

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

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

$txItem = new MigrationTransactionItem();
$txItem->setItemType('NonRecurringCharge');
$txItem->setMigrationTaxItems(array($taxItemA, $taxItemB));
$txItem->setName('ONE TIME CHARGE');
$txItem->setPrice(49.99);
$txItem->setSku('CB-4081');
$txItem->setTaxClassification('DC010500');

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

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

$creditCardStatusB = new CreditCardStatus();
$creditCardStatusB->setAutCode('000');
$statusLogB = new TransactionStatus();
$statusLogB->setCreditCardStatus($creditCardStatusB);
$statusLogB->setPaymentMethodType('CreditCard');
$statusLogB->setStatus('Authorized');
$statusLogB->setTimestamp('2014-02-06T13:21:33-08:00');

$statusLogC = new TransactionStatus();
$statusLogC->setPaymentMethodType('CreditCard');
$statusLogC->setStatus('New');
$statusLogC->setTimestamp('2014-02-06T13:21:23-08:00');

$migrationTransaction = new MigrationTransaction();
$migrationTransaction->setAccount($account);
$migrationTransaction->setAmount(41.08);
$migrationTransaction->setCurrency('USD');
$migrationTransaction->setDivisionNumber('iAmTheWalrus');
$migrationTransaction->setMerchantAffiliateId('Joe');
$migrationTransaction->setMerchantAffiliateSubId('Bob');
$migrationTransaction->setMerchantTransactionId('mTXID-1391721679-1');
$migrationTransaction->setMigrationTransactionItems(array($txItem));
$migrationTransaction->setPaymentMethod($paymentMethod);
$migrationTransaction->setPaymentProcessor('Litle');
$migrationTransaction->setPaymentProcessorTransactionId('1069127');
$migrationTransaction->setSalesTaxAddress($address);
$migrationTransaction->setShippingAddress($address);
$migrationTransaction->setSourceIp('63.201.132.182');
$migrationTransaction->setStatusLog(array($statusLogA, $statusLogB, $statusLogC));
$migrationTransaction->setType('NonRecurring');

//Migrate Transaction into CashBox

$response = $transaction->migrate(array($migrationTransaction));
if($response['returnCode'] == 200)
{

//Transaction(s) migrated successfully

}
else
{

//One or more Transaction migrations failed.
//Rummage through the TransactionValidationResponse objects
//in the $response to determine the source of the problem(s)

}

For Users

Learn More
For Users

Cashbox Features

Learn More
Cashbox Features
Back to Top