www.jBilling.

com

The Open Source Enterprise Billing System

Integration Guide
Copyright

This document is Copyright © 2004-2010 Enterprise jBilling Software Ltd. All Rights
Reserved. No part of this document may be reproduced, transmitted in any form or by
any means -electronic, mechanical, photocopying, printing or otherwise- without the prior
written permission of Enterprise jBilling Software Ltd.
jBilling is a registered trademark of Enterprise jBilling Software Ltd. All other brands and
product names are trademarks of their respective owners.

Author
Emir Calabuch and others

Revision number and software version

This revision is 1.4, based on jBilling 2.1.0
 Table of Contents

CHAPTER 1
INTRODUCTION..................................................................................................11
Scope..............................................................................................................................................................12

Requirements................................................................................................................................................12

The Need for Integration..............................................................................................................................13

Preparing jBilling for Integration...............................................................................................................13

Configuring a Remoting Method...............................................................................................................13
Securing Integration Access.......................................................................................................................14
Overview................................................................................................................................................14
Enabling/Disabling authentication for jBilling web services................................................................14
Enabling/Disabling company security checks.......................................................................................15
Enabling SSL for jBilling web services.................................................................................................15
Setting up jBilling to accept external calls.................................................................................................15
Connecting to jBilling............................................................................................................................16
SOAP.................................................................................................................................................16
Hessian/Burlap..................................................................................................................................17
Java RMI...........................................................................................................................................17

CHAPTER 2
INTEGRATING JBILLING TO YOUR APPLICATION.........................................18
Overview........................................................................................................................................................19

The jBilling Client API.................................................................................................................................19

The advantages of using jBilling client API..............................................................................................20
Using the jBilling Client API.....................................................................................................................21
Configuration.............................................................................................................................................22
The SOAP (CXF) Web Services Method..................................................................................................22
Properties...............................................................................................................................................23
The Hessian/Burlap Method.......................................................................................................................23
Properties...............................................................................................................................................23
Java RMI....................................................................................................................................................23
Properties...............................................................................................................................................23

Integration with non-Java Applications.....................................................................................................24

 Integration with C# .NET...........................................................................................................................24
Integration with PHP..................................................................................................................................25

CHAPTER 3
AN INTEGRATION TUTORIAL............................................................................27
Overview........................................................................................................................................................28

The Trend Website.......................................................................................................................................28

Controlling Entrance to the Paid Area of the Website...............................................................................28
Trial Period Management...........................................................................................................................30
Contact Information...................................................................................................................................34
Custom Contact Fields...........................................................................................................................34
Updating and Deleting Users and Orders...................................................................................................35
The user's “main” order.........................................................................................................................36
A word on pricing......................................................................................................................................37
Keeping jBilling in sync with your data.....................................................................................................39
Subscription status.................................................................................................................................39
Setting up Call Backs.............................................................................................................................40

Conclusion.....................................................................................................................................................42

CHAPTER 4
CLIENT API REFERENCE...................................................................................43
Overview........................................................................................................................................................44

User Management Calls...............................................................................................................................44

Data Structures...........................................................................................................................................44
UserWS..................................................................................................................................................44
CreditCardDTO......................................................................................................................................47
ContactWS.............................................................................................................................................47
UserTransitionResponseWS..................................................................................................................49
Methods......................................................................................................................................................49
authenticate............................................................................................................................................49
Input Parameters................................................................................................................................49
Return Value......................................................................................................................................49
createUser..............................................................................................................................................50
Input Parameters................................................................................................................................50
Return Value......................................................................................................................................50
deleteUser..............................................................................................................................................50
Input Parameters................................................................................................................................50
 Return Value......................................................................................................................................50
updateUserContact.................................................................................................................................50
Input Parameters................................................................................................................................50
Return Value......................................................................................................................................51
updateUser.............................................................................................................................................51
Input Parameters................................................................................................................................51
Return Value......................................................................................................................................51
getUserWS.............................................................................................................................................51
Input Parameters................................................................................................................................51
Return Value......................................................................................................................................51
getUserContactsWS...............................................................................................................................51
Input Parameters................................................................................................................................52
Return Value......................................................................................................................................52
getUserId................................................................................................................................................52
Input Parameters................................................................................................................................52
Return Value......................................................................................................................................52
getUsersInStatus....................................................................................................................................52
Input Parameters................................................................................................................................52
Return Value......................................................................................................................................52
getUsersNotInStatus..............................................................................................................................52
Input Parameters................................................................................................................................52
Return Value......................................................................................................................................53
getUsersByCustomField........................................................................................................................53
Input Parameters................................................................................................................................53
Return Value......................................................................................................................................53
getUsersByCreditCard...........................................................................................................................53
Input Parameters................................................................................................................................53
Return Value......................................................................................................................................53
updateCreditCard...................................................................................................................................53
Input Parameters................................................................................................................................53
Return Value......................................................................................................................................54
getUserTransitions.................................................................................................................................54
Input Parameters................................................................................................................................54
Return Value......................................................................................................................................54
getUserTransitionsAfterId.....................................................................................................................54
Input Parameters................................................................................................................................54
Return Value......................................................................................................................................54
isUserSubscribedTo...............................................................................................................................54
Input Parameters................................................................................................................................54
 Return Value......................................................................................................................................55

Order Management Calls.............................................................................................................................55

Data Structures...........................................................................................................................................55
OrderWS................................................................................................................................................55
OrderLineWS.........................................................................................................................................58
CreateResponseWS................................................................................................................................60
PricingField............................................................................................................................................60
Methods......................................................................................................................................................62
create......................................................................................................................................................62
Input Parameters................................................................................................................................62
Return Value......................................................................................................................................62
createOrderPreAuthorize.......................................................................................................................62
Input Parameters................................................................................................................................63
Return Value......................................................................................................................................63
createOrder.............................................................................................................................................63
Input Parameters................................................................................................................................64
Return Value......................................................................................................................................64
createOrderAndInvoice..........................................................................................................................64
Input Parameters................................................................................................................................64
Return Value......................................................................................................................................64
updateOrder............................................................................................................................................64
Input Parameters................................................................................................................................65
Return Value......................................................................................................................................65
getOrder.................................................................................................................................................65
Input Parameters................................................................................................................................65
Return Value......................................................................................................................................65
rateOrder................................................................................................................................................65
Input Parameters................................................................................................................................65
Return value.......................................................................................................................................65
rateOrders...............................................................................................................................................65
Input Parameters................................................................................................................................65
Return value.......................................................................................................................................66
getOrderByPeriod..................................................................................................................................66
Input Parameters................................................................................................................................66
Return Value......................................................................................................................................66
getOrderLine..........................................................................................................................................66
Input Parameters................................................................................................................................66
Return Value......................................................................................................................................66
 updateOrderLine....................................................................................................................................66
Input Parameters................................................................................................................................66
Return Value......................................................................................................................................66
getLatestOrder........................................................................................................................................67
Input Parameters................................................................................................................................67
Return Value......................................................................................................................................67
getLastOrders.........................................................................................................................................67
Input Parameters................................................................................................................................67
Return Value......................................................................................................................................67
deleteOrder.............................................................................................................................................67
Input Parameters................................................................................................................................67
Return Value......................................................................................................................................67
getCurrentOrder.....................................................................................................................................67
Input Parameters................................................................................................................................68
Return Value......................................................................................................................................68
updateCurrentOrder...............................................................................................................................68
Input Parameters................................................................................................................................68
Returns...............................................................................................................................................69
getLatestOrderByItemType...................................................................................................................69
Input Parameters................................................................................................................................69
Returns...............................................................................................................................................69
getLastOrdersByItemType.....................................................................................................................69
Input Parameters................................................................................................................................69
Returns...............................................................................................................................................69

Item Management Calls...............................................................................................................................69

Data Structures...........................................................................................................................................70
ItemDTOEx............................................................................................................................................70
ItemPriceDTOEx...................................................................................................................................71
ItemTypeWS..........................................................................................................................................72
ValidatePurchaseWS..............................................................................................................................72
Methods......................................................................................................................................................72
createItem...............................................................................................................................................72
Input Parameters................................................................................................................................72
Return Value......................................................................................................................................73
getItem...................................................................................................................................................73
Input Parameters................................................................................................................................73
Return Value......................................................................................................................................73
getAllItems.............................................................................................................................................73
 Input Parameters................................................................................................................................73
Return Value......................................................................................................................................73
getAllItemCategories.............................................................................................................................74
Input Parameters................................................................................................................................74
Return Value......................................................................................................................................74
getItemByCategory................................................................................................................................74
Input Parameters................................................................................................................................74
Return Value......................................................................................................................................74
updateItem..............................................................................................................................................74
Input Parameters................................................................................................................................74
Return Value......................................................................................................................................74
getUserItemsByCategory.......................................................................................................................74
Input Parameters................................................................................................................................75
Return Value......................................................................................................................................75
validatePurchase....................................................................................................................................75
Input Parameters................................................................................................................................75
Return Value......................................................................................................................................75
validateMultiPurchase............................................................................................................................75
Input Parameters................................................................................................................................76
Return Value......................................................................................................................................76

Invoice Management Calls...........................................................................................................................76

Data Structures...........................................................................................................................................76
InvoiceWS..............................................................................................................................................76
InvoiceLineDTO................................................................................................................................78
Methods......................................................................................................................................................79
getInvoiceWS.........................................................................................................................................79
Input Parameters................................................................................................................................79
Return Value......................................................................................................................................79
deleteInvoice..........................................................................................................................................80
Input Parameters................................................................................................................................80
Return Value......................................................................................................................................80
getLatestInvoice.....................................................................................................................................80
Input Parameters................................................................................................................................80
Return Value......................................................................................................................................80
getLastInvoices......................................................................................................................................80
Input Parameters................................................................................................................................80
Return Value......................................................................................................................................80
getInvoicesByDate.................................................................................................................................81
 Input Parameters................................................................................................................................81
Return Value......................................................................................................................................81
getUserInvoicesByDate.........................................................................................................................81
Input Parameters................................................................................................................................81
Return Value......................................................................................................................................81
createInvoice..........................................................................................................................................82
Input Parameters................................................................................................................................82
Return Value......................................................................................................................................82
getLatestInvoiceByItemType.................................................................................................................82
Input Parameters................................................................................................................................82
Returns...............................................................................................................................................82
getLastInvoicesByItemType..................................................................................................................82
Input Parameters................................................................................................................................82
Returns...............................................................................................................................................83

Payment Management Calls........................................................................................................................83

Data Structures.......................................................................................................................................83
PaymentWS.......................................................................................................................................83
PaymentInfoChequeDTO..................................................................................................................85
AchDTO............................................................................................................................................86
PaymentAuthorizationDTO...............................................................................................................86
PaymentAuthorizationDTOEx..........................................................................................................87
Methods......................................................................................................................................................87
applyPayment.........................................................................................................................................87
Input Parameters................................................................................................................................87
Return Value......................................................................................................................................87
payInvoice..............................................................................................................................................87
Input Parameters................................................................................................................................88
Return Value......................................................................................................................................88
getPayment.............................................................................................................................................88
Input Parameters................................................................................................................................88
Return Value......................................................................................................................................88
getLatestPayment...................................................................................................................................88
Input Parameters................................................................................................................................88
Return Value......................................................................................................................................88
getLastPayments....................................................................................................................................88
Input Parameters................................................................................................................................89
Return Value......................................................................................................................................89
processPayment......................................................................................................................................89
 Input Parameters................................................................................................................................89
Return Value......................................................................................................................................89

APPENDIX A
CONSTANTS REFERENCE................................................................................90
Language Codes.........................................................................................................................................91
Currency Codes..........................................................................................................................................91
Role Codes.................................................................................................................................................91
User Status Codes.......................................................................................................................................92
Subscriber Status Codes.............................................................................................................................92
Payment Method Codes.............................................................................................................................93
Order Status Codes.....................................................................................................................................93
Order Billing Type Codes..........................................................................................................................93
Order Line Type Codes..............................................................................................................................94
Invoice Status Codes..................................................................................................................................94
Period units (units of time).........................................................................................................................94
Payment results .........................................................................................................................................94
Dynamic Balance Codes............................................................................................................................95
Provisioning Status Codes..........................................................................................................................95