CashBox 24.1.0: Programming Guide CashBox® Programming Guide CashBox 24.1.0 May 2019 © 2019 Vindicia, Inc. Table of Contents 1 - a CashBox 24.1.0: Programming Guide Copyright © 2006 – 2019 by Vindicia, Inc. All rights reserved. Restricted Rights Build Online Revenue, CashBox, CashBox DataBridge, CashBox Insight, CashBox Select, CashBox StoreFront, ChargeGuard, Marketing and Selling Automation for the Digital Economy, Vindicia, Your Chargebacks. Our Problem., and all related logos are trademarks or registered trademarks of Vindicia, Inc. All other company and product names may be trademarks of their respective owners. This document may contain statements of future direction concerning possible functionality for Vindicia's software products and technology. All functionality and software products will be available for license and shipment from Vindicia only if and when generally commercially available. Vindicia disclaims any express or implied commitment to deliver functionality or software unless or until actual shipment of the functionality or software occurs. The statements of possible future direction are for information purposes only, and Vindicia makes no express or implied commitments or representations concerning the timing and content of any future functionality or releases. This document is subject to change without notice, and Vindicia does not warrant that the material contained in this document is error-free. If you find any problems with this document, please report them to Vindicia in writing. No part of this document may be reproduced or transmitted in any form or by any means, electronic or mechanical, including photocopying and recording, for any purpose without the express written permission of Vindicia, Inc. The information contained in this document is proprietary and confidential to Vindicia, Inc. June 28, 2019 © 2019 Vindicia, Inc. Table of Contents 1 - b CashBox 24.1.0: Programming Guide CashBox® Programming Guide Preface About CashBox. ii About ChargeGuard . iii Chapter 1 CashBox Client Library Setup. 1-1 1.1 CashBox API . 1-2 1.2 Support for Development . 1-3 1.2.1 Installing and Configuring the CashBox Library . 1-3 PHP . 1-3 Perl . 1-4 Configuring the Perl API Client . 1-4 Specifying the First Parameter in Perl . 1-5 Java . 1-5 .NET With C# . 1-6 1.2.2 Setting Up Authentication Parameters . 1-6 In Perl . 1-7 In PHP . 1-7 In Java . 1-7 In VB . 1-8 In C# . 1-8 1.2.3 Configuring the SOAP Timeout for Client Libraries . 1-8 In PHP . 1-9 In Java . 1-9 In ASP, VB, and C++ . 1-9 In C# . 1-9 1.2.4 Checking an Object Method’s Return Value . 1-9 1.2.5 Working with Sparse Response Descriptions . 1-11 1.2.6 Setting UNIX Timestamps in VB . 1-11 1.2.7 Date and Timestamp Format . 1-12 1.2.8 Assigning Unique Identifiers for Objects . 1-12 1.2.9 Merchant Identifiers . 1-12 1.2.10 Ensuring the Correct Character Encoding . 1-13 1.3 Working with CashBox WSDL Files . 1-13 1.3.1 Specifying the SOAP Address . 1-14 1.3.2 Performing the Prerequisite Steps . 1-14 1.4 Tips for Developing SOAP Clients . 1-15 Chapter 2 Working with Accounts . 2-1 2.1 Creating Customer Accounts . 2-2 2.2 Setting Up Account Payment Methods . 2-3 2.3 Accessing Existing Customer Accounts . 2-6 © 2019 Vindicia, Inc. Table of Contents i - i CashBox 24.1.0: Programming Guide 2.4 Creating Account Hierarchies . 2-7 2.5 Presenting the Reason for Credit (to the customer) . 2-9 Chapter 3 Working with Products. 3-1 3.1 Creating Products . 3-2 3.2 Creating Bundled Products . 3-4 3.3 Accessing Existing Products . 3-5 Chapter 4 Working with Billing Plans. 4-1 4.1 Creating Billing Plans . 4-2 Chapter 5 Working with AutoBills. 5-1 5.1 Creating AutoBills . 5-2 5.1.1 Creating an AutoBill with Multiple Products . 5-5 5.1.2 Creating an AutoBill with Seasonal Billing . 5-6 5.1.3 Creating or Modifying AutoBills with Pre-Authorization . 5-6 5.1.4 Updating and Validating AutoBill Objects . 5-7 5.1.5 Verifying AVS and CVN for Recurring Billing . 5-8 5.2 Modifying AutoBills . 5-11 5.2.1 Prorating Modification-Based Price Changes . 5-11 5.2.2 Changing Products for an AutoBill . 5-12 5.2.3 Changing the Billing Plan for an AutoBill . 5-14 5.2.4 Changing both Products and Billing Plan in a Single Call . 5-15 5.2.5 Viewing AutoBill Changes . 5-16 5.2.6 Continuous Billing during Retry Period . 5-17 5.2.7 Advance and Arrears Billing Option for AutoBills . 5-17 5.3 Canceling AutoBills . 5-19 5.3.1 Canceling AutoBills with Reason Codes . 5-19 5.3.2 Creating Custom-Defined Merchant Cancel Reason Codes 5-21 5.3.3 Canceling AutoBills on Billing Day . 5-21 5.4 Importing AutoBills from other Billing Systems to CashBox . 5-22 5.4.1 Key Migrate Parameters . 5-23 5.4.2 Migrating an AutoBill During a Billing Cycle . 5-23 5.4.3 Migrating an AutoBill During a Free Trial Period . 5-28 5.5 Using EDD and UK DD for Recurring Billing . 5-30 5.5.1 Understanding Mandates for Recurring Billing with EDD . 5-33 5.5.2 Understanding Mandates for Recurring Billing with UK DD 5-34 5.6 Using PayPal for Recurring Billing . 5-35 © 2019 Vindicia, Inc. Table of Contents i - ii CashBox 24.1.0: Programming Guide Chapter 6 Working with One-Time Transactions . 6-1 6.1 Setting Up Real-Time Billing for One-Time Purchases . 6-2 6.1.1 Monitoring Transaction Status . 6-2 6.2 Using Credit Cards for One-Time Transactions . 6-3 6.2.1 Verifying AVS and CVN for One-Time Transactions . 6-5 6.2.2 Calling the auth and capture Methods Separately . 6-8 6.3 Using Carrier Billing for One-Time Transactions . 6-10 6.3.1 BOKU Static Pricing Transactions . 6-11 6.3.2 BOKU Dynamic Pricing Transactions . 6-12 6.3.3 Using CashBox to query BOKU . 6-13 6.4 Using Boleto Bancario for One-Time Transactions . 6-15 6.5 Using ECP for One-Time Transactions . 6-16 6.5.1 Creating Outbound Payment Transactions with ECP . 6-17 6.6 Using EDD and UK DD for One-Time Transactions . 6-19 6.6.1 Understanding Mandates for Real-Time Billing with EDD . 6-21 6.6.2 Understanding Mandates for Real-Time Billing with UK DD 6-23 6.7 Using PayPal for One-Time Transactions . 6-24 6.8 Recording a Payment Manually . 6-26 6.9 Importing Transactions from other Billing Systems to CashBox . 6-28 6.10 Refunding Customers . 6-29 Chapter 7 Working with Entitlements. 7-1 7.1 Creating Entitlements . 7-2 7.2 Entitlement Status . 7-3 7.3 Caching Entitlements . 7-3 7.4 Monitoring Entitlement Status . 7-4 Chapter 8 Working with Rate Plans . 8-1 8.1 Recording Rated Units . 8-2 8.2 Deducting Rated Units . 8-4 8.3 Reversing (Billed) Rated Unit Events . 8-4 8.4 Fetching and Reporting Rated Units . 8-5 8.4.1 Fetching a Summary (Total) of Unbilled Rated Unit Events 8-5 8.4.2 Fetching Billed or Unbilled Rated Unit Events . 8-7 8.5 Understanding License Based Quantities . 8-9 © 2019 Vindicia, Inc. Table of Contents i - iii CashBox 24.1.0: Programming Guide Chapter 9 Working with Customer Notifications. 9-1 9.1 Setting the Preferred Language . 9-2 9.2 Working with Billing Events . 9-2 9.2.1 CashBox Billing Events . 9-2 9.2.2 Billing Event Settings . 9-5 9.2.3 Parent-Child Account Billing Notifications . 9-6 9.2.4 Creating Billing Notification Templates . 9-7 Billing Event Template Tags . ..