BillingOrchard API Documentation

Tap into our Billing System



    API DOCUMENTATION

  • JSON Format
  • CheckOut Function
  • View Function
  • Delete Function
  • Update Function
  • Add Function
  • JSON Fields for Add/Edit
  • Direct Post
API Access

To access the API, use the following URL
https://billingorchardapi.com/webservice/ChooseService.php

JSON Format

The five functions described below expect a single post variable called jsonData in json format. The CheckOut,Add, and Edit functions have an additional "object" key that contains data necessary for the function to accomplish its task, shown below. Please reference the "JSON Fields for Add and Edit" for the proper key names.

{
"apikey":"data",
"service":"ViewUsers",
"sig":"HMAC Signature",
"timestamp":"20120802 15:47",
	"object":{
	"key":"data",
	"key2":"data2"
	}
}
HMAC-SHA256 Signature

The HMAC Signature input is generated from appending the apikey, service, and timestamp values together. (e.g. $apikey.$service.$timestamp) The timestamp shall consist of the time the data is called in the format of "YYYYMMDD hh:mm" in Coordinated Universal Time (UTC). If the request is five minutes old when it gets processed by the server or the signature is incorrect, it will return a 401 not authorized. The hashing algorithm is currently set as sha256. The key is currently set as "BillingOrchard2012".

The signature is encoded into a base64 string that complies with established standards.

Checkout function

Procedure

  1. Call ChooseService.php
  2. JSON Keys
    1. service
      • CheckOut
    2. apikey
    3. sig
    4. timestamp
    5. object
      • "AmountPaid":"45.45"
      • BilledMisc data - no invoice number
      • "ClientID" or client information
  3. Expected Output
    1. Wrong or invalid apikey
      • "Message":"Error with apikey"
    2. Error with selecting service
      • "Message":"Error selecting service"
    3. Successful and all IDs are returned
      • "Message":"success"
      • "ClientID":""
      • "Invoice":""
      • "Fee":""
      • "Recurring":""
      • "Payment":""
    4. Error adding or editing client
      • "Message":"Error with Creating Client"
    5. Error with adding or editing client vault account
      • "Message":"NMI Error with Client"
      • "Response_code":200|300|etc
    6. Error creating Invoice
      • "Message":"Error with Creating Invoice"
      • "ClientID":""
    7. Error creating BilledMisc Fee
      • "Message":"Error with Creating Fee"
      • "ClientID":""
      • "Invoice":""
    8. Error creating RecurringBilling
      • "Message":"Error with Creating Recurring"
      • "ClientID":""
      • "Invoice":""
      • "Fee":""
    9. Error processing payment
      • "Message":"NMI Error with Processing Payment"
      • "Response_code":200|300|etc
      • "ClientID":""
      • "Invoice":""
      • "Fee":""
      • "Recurring":""
    10. Error creating payment entry in billingorchard database
      • "Message":"Error with Creating Payment Record but it has been processed"
      • "ClientID":""
      • "Invoice":""
      • "Fee":""
      • "Recurring":""
View function

Procedure

  1. Call ChooseService.php
  2. JSON Keys
    1. service
      • ViewUsers
      • ViewClients
      • ViewHourlyServices
      • ViewInvoices
      • ViewPayments
      • ViewBilledMisc
      • ViewBilledHourly
      • ViewSubscribers
      • ViewRecurringBilling
    2. apikey
    3. sig
    4. timestamp
    5. ID
      • optional field that expects the id number of the item, not passing an id will return all items associated with the apikey
  3. Expected Output
    1. Wrong or invalid apikey
      • "Message":"Error with apikey"
    2. Error with selecting service
      • "Message":"Error selecting service"
    3. Outputs the selected data
Delete function

Procedure

  1. Call ChooseService.php
  2. JSON Keys
    1. service
      • DeleteClients
      • DeleteHourlyServices
      • DeleteInvoices
      • DeleteBilledMisc
      • DeleteBilledHourly
      • DeleteMiscItems
      • DeleteRecurringBilling
    2. apikey
    3. sig
    4. timestamp
    5. ID
      • ID used to identify item being deleted
  3. Expected Output
    1. Wrong or invalid apikey
      • "Message":"Error with apikey"
    2. Error with selecting service
      • "Message":"Error selecting service"
    3. JSON output with key "Message"
      • "Message":"success"
      • "Message":"DeleteFail"
Edit function

Procedure

  1. Call ChooseService.php
  2. JSON Keys
    1. service
      • UpdateClients
      • UpdateHourlyServices
      • UpdateInvoices
      • UpdateBilledMisc
      • UpdateBilledHourly
      • UpdateMiscItems
      • UpdateSubscribers
      • UpdateRecurringBilling
    2. apikey
    3. sig
    4. timestamp
    5. object
  3. Expected Output
    1. Wrong or invalid apikey
      • "Message":"Error with apikey"
    2. Error with selecting service
      • "Message":"Error selecting service"
    3. JSON output with key "Message"
      • "Message":"success"
      • "Message":"UpdateFail"
Add function

Procedure

  1. Call ChooseService.php
  2. JSON Keys
    1. service
      • AddClients
      • AddHourlyServices
      • AddInvoices
      • AddPayments
      • AddBilledMisc
      • AddBilledHourly
      • AddMiscItems
      • AddSubscribers
      • AddRecurringBilling
    2. apikey
    3. sig
    4. timestamp
    5. object
  3. Expected Output
    1. Wrong or invalid apikey
      • "Message":"Error with apikey"
    2. Error with selecting service
      • "Message":"Error selecting service"
    3. Output with "Message" and id of newly added item
      • "Message":"success"
      • "ID":"1234"
    4. Output with "Message" and id of newly added item but submitting to gateway resulted in error
      • "Message":"success"
      • "ID":"1234"
      • "Response_code":"300"
    5. Add Failure
      • "Message":"AddFail"
CheckOut function

This function takes the data for a client, billed misc fees, and the amount being charged. It takes this and creates a new invoice, payment, and a client if the ClientID is not passed but the client information is. It uses this information to charge a payment using the client's payment information.

Parameters

Parameters are the data you will pass with the call.

Service

For the CheckOut function, this field must contain "CheckOut"

Rules: Required
Type: String


apikey

This is your identifier

Rules: Required
Type: String


sig

The HMAC-SHA256 Signature input is generated from appending the apikey, service, and timestamp values together as the input and your private key as the key

Rules: Required
Type: String


timestamp

The time that the function was called. It must be in YYYYMMDD HH:MM format in UTC

Rules: Required
Type: String


object

This contains the necessary data for the function to do its job.

  • ClientID or all relevant new client information (Refer to Add function for Clients)
  • All BilledMisc information except for the InvoiceNumber (Refer to Add function for BilledMisc)
  • "AmountPaid":"50.24", this field must contain the amount that the client will be charged

Rules: Required
Type: String


Return Values

A JSON string is returned containing a message and other data.

Error with apikey

There is an issue with the apikey.


Error selecting service

The service name provided could not be found.


success

The function was successful. It returns the IDs of five items. ClientID, Invoice, Fee, Recurring, and Payment.


Error with Creating Client

There was an issue with the data that prevented the system from add or editing a client


NMI Error with Client

There was a problem with updating or adding a client in the customer vault. A "Response_code" is returned that will describe the problem


Error with Creating Invoice

Problem with creating Invoice. ClientID is returned


Error with Creating Fee

Problem with creating a BilledMisc fee. ClientID and Invoice are returned


Error with Creating Recurring

Problem with creating a RecurringBilling fee. ClientID, Invoice, and Fee are returned


NMI Error with Processing Payment

Error with processing the payment. A "Response_code" is returned that will describe the problem. ClientID, Invoice, Fee, and Recurring IDs are returned


Error with Creating Payment Record but it has been processed

There was a problem creating a payment entry in the database. ClientID, Invoice, Fee, and Recurring IDs are returned

View Function

Parameters

Parameters are the data you will pass with the call.

Service

For the View function, this field must contain one of the following:

  • ViewUsers
  • ViewClients
  • ViewHourlyServices
  • ViewInvoices
  • ViewPayments
  • ViewBilledMisc
  • ViewMiscItems
  • ViewBilledHourly
  • ViewSubscribers
  • ViewRecurringBilling

Rules: Required
Type: String


apikey

This is your identifier

Rules: Required
Type: String


sig

The HMAC-SHA256 Signature input is generated from appending the apikey, service, and timestamp values together as the input and your private key as the key

Rules: Required
Type: String


timestamp

The time that the function was called. It must be in YYYYMMDD HH:MM format in UTC

Rules: Required
Type: String


ID

If this field is specified, it will return the specified corresponding item

Rules: Optional


Return Values

A JSON string is returned containing a message and other data.

Error with apikey

There is an issue with the apikey.


Error selecting service

The service name provided could not be found.


Outputs data

The function was successful and returns the data

Delete Function

Parameters

Parameters are the data you will pass with the call.

Service

For the Delete function, this field must contain one of the following

  • DeleteClients
  • DeleteHourlyServices
  • DeleteInvoices
  • DeleteBilledMisc
  • DeleteMiscItems
  • DeleteBilledHourly
  • DeleteRecurringBilling

Rules: Required
Type: String


apikey

This is your identifier

Rules: Required
Type: String


sig

The HMAC-SHA256 Signature input is generated from appending the apikey, service, and timestamp values together as the input and your private key as the key

Rules: Required
Type: String


timestamp

The time that the function was called. It must be in YYYYMMDD HH:MM format in UTC

Rules: Required
Type: String


ID

ID used to identify item being deleted

Rules: Required
Type: Integer


Return Values

A JSON string is returned containing a message and other data.

Error with apikey

There is an issue with the apikey.


Error selecting service

The service name provided could not be found.


success or DeleteFail

Delete status message

Update Function

Parameters

Parameters are the data you will pass with the call.

Service

For the Update function, this field must contain one of the following

  • UpdateClients
  • UpdateHourlyServices
  • UpdateInvoices
  • UpdateBilledMisc
  • UpdateMiscItems
  • UpdateBilledHourly
  • UpdateSubscribers
  • UpdateRecurringBilling

Rules: Required
Type: String


apikey

This is your identifier

Rules: Required
Type: String


sig

The HMAC-SHA256 Signature input is generated from appending the apikey, service, and timestamp values together as the input and your private key as the key

Rules: Required
Type: String


timestamp

The time that the function was called. It must be in YYYYMMDD HH:MM format in UTC

Rules: Required
Type: String


object

This contains the necessary data for the function to do its job.

  • ClientID or all relevant new client information (Refer to Add function for Clients)
  • All BilledMisc information except for the InvoiceNumber (Refer to Add function for BilledMisc)
  • "AmountPaid":"50.24", this field must contain the amount that the client will be charged

Rules: Required


Return Values

A JSON string is returned containing a message and other data.

Error with apikey

There is an issue with the apikey.


Error selecting service

The service name provided could not be found.


success or UpdateFail

Update status message

Add Function

Parameters

Parameters are the data you will pass with the call.

Service

For the Add function, this field must contain one of the following

  • AddClients
  • AddHourlyServices
  • AddInvoices
  • AddPayments
  • AddBilledMisc
  • AddMiscItems
  • AddBilledHourly
  • AddSubscribers
  • AddRecurringBilling

Rules: Required
Type: String


apikey

This is your identifier

Rules: Required
Type: String


sig

The HMAC-SHA256 Signature input is generated from appending the apikey, service, and timestamp values together as the input and your private key as the key

Rules: Required
Type: String


timestamp

The time that the function was called. It must be in YYYYMMDD HH:MM format in UTC

Rules: Required
Type: String


object

This contains the necessary data for the function to do its job.

  • ClientID or all relevant new client information (Refer to Add function for Clients)
  • All BilledMisc information except for the InvoiceNumber (Refer to Add function for BilledMisc)
  • "AmountPaid":"50.24", this field must contain the amount that the client will be charged

Rules: Required


Return Values

A JSON string is returned containing a message and other data.

Error with apikey

There is an issue with the apikey.


Error selecting service

The service name provided could not be found.


success or AddFail

Add status message

JSON Fields for Add and Edit

These keys go under the object field of the json string. This section describes the required field name, the data type, and the character limit for each field.
NOTE: The respective ID field for each item type is not needed when doing an Add
Note 2: The format for smalldatetime is "YYYY-MM-DD HH:MM:SS"

  1. Users
    • UserID:integer:10
    • Name:string:30
    • Department:string:15
    • Email:string:50
    • UserLogin:string:60
    • UserPassword:string:15
    • Admin:1 or 0:1
    • Support:1 or 0:1
    • Active:1 or 0:1
  2. Clients
    • ClientID:integer:10
    • ClientLogin:string:60
    • ClientPassword:string:15
    • Client:string:75
    • Email:string:60
    • Tel:string:20
    • Fax:string:20
    • Contact:string:40
    • Address:string:50
    • Address2:string:50
    • City:string:30
    • State:string:20
    • Zip:string:10
    • Country:string:30
    • LastLogin:smalldatetime:16
    • Active:1 or 0:1
    • Notes:string:1073741823
    • CustomField:string:30
    • CustomFieldValue:string:30
    • ReceiveMail:1 or 0:1
    • NextBillDate:smalldatetime:16
    • FreqUnit:string:4
    • FreqDuration:integer:10
    • AutoCharge:1 or 0:1
    • ClientCard:string:50
    • ClientExp:string:10
    • ClientCardType:string:16
    • ClientFirstName:string:30
    • ClientLastName:string:40
    • DateDeleted:smalldatetime:16
    • GST:1 or 0:1
    • PST:1 or 0:1
    • HST:1 or 0:1
    • PSTCompound:1 or 0:1
    • GSTRate:decimal:24
    • PSTRate:decimal:24
    • HSTRate:decimal:24
    • CustomFieldTwo:string:20
    • DefaultRate:decimal:24
    • BankAcctFirstName:string:30
    • BankAcctLastName:string:30
    • BankAcctRoutingNum:string:30
    • BankAcctNum:string:30
    • BankAcctHolderType:string:20
    • BankAcctType:string:20
    • AutoChargeACH:1 or 0:1
    • CustomField2:string:55
    • CustomFieldValue2:string:55
    • CustomField3:string:55
    • CustomFieldValue3:string:55
    • CustomField4:string:55
    • CustomFieldValue4:string:55
    • CellNum:string:10
  3. HourlyServices
    • ItemID:integer:10
    • Service:string:30
    • Description:string:1073741823
    • HourlyRate:decimal:24
    • Taxable:1 or 0:1
  4. Invoices
    • ClientID:integer:10
    • InvoiceDate:smalldatetime:16
    • DueDate:smalldatetime:16
    • Notes:string:1073741823
    • HowSent:string:50
    • Terms:string:1073741823
    • TotalCost:money (45.45):19
    • OutstandingAmount:money (45.45):19
    • UserID:integer:10
    • InvoiceCustom:integer:10
    • TotalTax:money (45.45):10
    • ProjectID:integer:10
    • LastChargeDate:smalldatetime:16
    • Resent:1 or 0:1
    • LastResendDate:smalldatetime:16
  5. Payments
    • PaymentID:integer:10
    • Invoice:integer:19
    • ClientID:integer:10
    • AmountPaid:decimal:24
    • PaymentDate:smalldatetime:16
    • Notes:string:1073741823
    • AmountPaidBalance:decimal:24
  6. BilledMisc
    • BMID:integer:10
    • UserID:integer:10
    • ClientID:integer:10
    • DateCompleted:smalldatetime:16
    • Qty:decimal:24
    • Title:string:50
    • Description:string:1073741823
    • Invoiced:1 or 0:1
    • InvoiceNumber:integer:19
    • Taxable:1 or 0:1
    • Rate:decimal:24
    • ProjectID:integer:10
  7. MiscItems
    • MiscID:integer:10
    • Item:string:53
    • Description:string:1073741823
    • Rate:decimal:24
    • Taxable:1 or 0:1
  8. BilledHourly
    • BHID:integer:10
    • UserID:integer:10
    • DateCompleted:smalldatetime:16
    • ClientID:integer:10
    • Service:string:50
    • Hours:decimal:24
    • Rate:decimal:24
    • Description:string:1073741823
    • Invoiced:1 or 0:1
    • InvoiceNumber:integer:19
    • Taxable:1 or 0:1
    • ProjectID:integer:10
  9. Subscribers
    • Company:string:50
    • Email:string:60
    • Tel:string:20
    • Contact:string:40
    • TrialSignupDate:smalldatetime:16
    • TrialVersion:1 or 0:1
    • Active:1 or 0:1
    • PID:string:35
    • PaidUntilDate:smalldatetime:16
  10. RecurringBilling
    • RBID:integer:10
    • UserID:integer:10
    • ClientID:integer:10
    • DateCompleted:smalldatetime:16
    • Qty:decimal:24
    • Title:string:50
    • Description:string:1073741823
    • Taxable:1 or 0:1
    • Rate:decimal:24
    • NextBillingDate:smalldatetime:16
    • FrequencyUnit:string:4
    • FrequencyDuration:integer:10
    • ProjectID:integer:10
Direct Post

The direct post function is an alternative to posting a single JSON string to the API. In order to direct post to the BillingOrchard API, you must post the following variables to "https://billingorchardapi.com/webservice/Direct.php"

  • apikey
  • sig
  • timestamp
  • service
  • Other variables related to the service that is being called