Developer REST JSON API

In addition to our easy-to-use interface, a large amount of ChargeOver functionality is exposed via a REST JSON API.

Finding your API Endpoint

The first step towards integration is finding your endpoint and credentials.

  1. Log in to ChargeOver, and navigate to this menu option:
  2. Configuration > API & Web Hooks
  3. Enable the API, and find your API endpoint at the bottom of the screen. Click the Save button to save the configuration.

API Authentication

All API calls are made over a secure SSL/HTTPS connection. In addition to the point-to-point encryption SSL/HTTPS provides, ChargeOver offers two different options for authentication.

The easiest way to get started with the API is to use standard “HTTP Basic Auth”. This uses the industry-standard HTTP authentication to authenticate access to the REST API.

If you need more security, ChargeOver also offers a signed, HMAC-SHA256 based authentication method. The advantages of the signature-based approach are:

  1. Protection against replay attacks
  2. Verification that the API request you sent was not altered during transport
  3. No need to transmit your private API key over the wire

We recommend you develop using HTTP basic auth, and then migrate to using signatures in production environments.

Getting Started

Visit this URL to make your first API request:

(substitute your own application/domain name into the above string!)

To retrieve a list of data from ChargeOver, use a HTTP GET request:

To retrieve a subset of the items in a list (e.g. records 10 to 25) you can use the offset and limit parameters (just like in an SQL database):

To retrieve a specific record from ChargeOver, use a HTTP GET request and specify the record id:

To add a new record to ChargeOver, use a HTTP POST request:

POST /api/v3/customer HTTP/1.1
Authorization: Basic N3N1dFdGRU8yektWWUlHbVpNSjNOaWo1aGZMeERSYjg6OXZDSmJtZFpLU2llVmNoeXJSSXRGUXc4TUJONGxPSDM=
Host: CHANGE-THIS.chargeover.com
Content-Length: 186

{
  "company": "Test JSON Company",
  "bill_addr1": "16 Dog Lane",
  "bill_addr2": "Suite D",
  "bill_city": "Storrs",
  "bill_state": "CT",
  "email": "keith@chargeover.com"
}

To update an existing record in ChargeOver, use a HTTP PUT request, and specify the record id in the URL:

PUT /api/v3/customer/1 HTTP/1.1
Authorization: Basic N3N1dFdGRU8yektWWUlHbVpNSjNOaWo1aGZMeERSYjg6OXZDSmJtZFpLU2llVmNoeXJSSXRGUXc4TUJONGxPSDM=
Host: dev.chargeover.com
Content-Length: 191

{
  "company": "Update This Record 755",
  "bill_addr1": "16 Dog Lane",
  "bill_addr2": "Suite D",
  "bill_city": "Storrs",
  "bill_state": "CT",
  "email": "keith@chargeover.com"
}

You can also do more advanced queries by specifying additional parameters:

  • /api/v3/customer?where=external_key:EQUALS:some-value
  • /api/v3/customer?where=external_key:IS:NULL
  • /api/v3/customer?where=external_key:IS:NULL&limit=100
  • /api/v3/customer?where=bill_state:EQUALS:CT
  • /api/v3/customer?where=external_key:EQUALS:abcd1234,bill_state:EQUALS:CT

The API also supports sorting by specifying a sort parameter:

  • /api/v3/customer?order=customer_id:DESC
  • /api/v3/customer?order=customer_id:ASC
  • /api/v3/customer?order=bill_country:ASC,customer_id:DESC

API Data/Resources

Customers

The primary key field for a customer is: customer_id

  • Get a list of customers – GET /api/v3/customer
  • Get a specific customer – GET /api/v3/customer/1234 (where 1234 is the customer_id value)
  • Query for customers – GET /api/v3/customer?where=... (available parameters: external_key, company, bill_state, ship_state, bill_country, ship_country)
  • Add a customer – POST /api/v3/customer
  • Update a customer – PUT /api/v3/customer/1234 (where 1234 is the customer_id value)
  • Delete a customer - DELETE /api/v3/customer/1234 (where 1234 is the customer_id value)

Users

The primary key field for a user is: user_id

  • Get a list of users – GET /api/v3/user
  • Get a specific user – GET /api/v3/user/1234 (where 1234 is the user_id value)
  • Add a user – POST /api/v3/user
  • Update a user – PUT /api/v3/user/1234 (where 1234 is the user_id value)
  • Reset/set a user’s password – POST /api/v3/user/1234?action=reset_password (where 1234 is the user_id value)

Invoices

The primary key field for an invoice is: invoice_id

  • Get a list of invoices – GET /api/v3/invoice
  • Get a specific invoice (with line items) – GET /api/v3/invoice/1234 (where 1234 is the invoice_id value)
  • Query for invoices – GET /api/v3/invoice?where=... (available parameters: customer_id, bill_state, ship_state, invoice_status_str, invoice_status_state)
  • Add an invoice – POST /api/v3/invoice
  • Attempt payment on an invoice (credit card) – POST /api/v3/invoice/1234?action=pay (where 1234 is the invoice_id value)
  • Attempt payment on an invoice (ACH/eCheck) – POST /api/v3/invoice/1234?action=pay (where 1234 is the invoice_id value)

Transactions (payments, refunds, credits)

The primary key field for a transaction is: transaction_id

  • Get a list of transactions – GET /api/v3/transaction
  • Get a specific transaction – GET /api/v3/transaction/1234 (where 1234 is the transaction_id value)
  • Add a payment transaction (mark an invoice as paid) – POST /api/v3/transaction

Billing Packages

The primary key field for a billing package is: billing_package_id

  • Get a list of billing packages – GET /api/v3/billing_package
  • Get a specific billing packages (with line items) – GET /api/v3/billing_package/1234 (where 1234 is the billing_package_id value)
  • Query for billing packages – GET /api/v3/billing_package?where=... (available parameters: customer_id, bill_state, ship_state, billing_package_status_str, billing_package_status_state)
  • Add a billing package – POST /api/v3/billing_package
  • Suspend a billing package – POST /api/v3/billing_package/1234?action=suspend (where 1234 is the billing_package_id value)
  • Upgrade/downgrade a billing package – POST /api/v3/billing_package/1234?action=upgrade (where 1234 is the billing_package_id value)

Items

The primary key field for items is: item_id

  • Get a list of items - GET /api/v3/item
  • Get a specific item - GET /api/v3/item/1234 (where 1234 is the item_id value)
  • Query for items - GET /api/v3/item?where=...
  • Add an item - POST /api/v3/item

Credit Cards

The primary key field for a credit card is: creditcard_id

  • Create/store a new credit card – POST /api/v3/creditcard
  • Update a credit card – PUT /api/v3/creditcard/1234 (where 1234 is the creditcard_id value)

ACH/eCheck Accounts

ACH/eCheck records are used to store banking information for ACH/eCheck payments.

The primary key field for an ACH record is: ach_id

Countries

  • Get a list of countries - GET /api/v3/country

Currencies

Usage Data/Units

Usage data can be used for metered billing and usage-based billing situations.

Notes

  • Add a note - POST /api/v3/note
  • Query for notes - GET /api/v3/note?where=obj_type:EQUALS:...,obj_id:EQUALS:... (you must specify an obj_type and a obj_id)

Reporting/Aggregation

ChargeOver supports an advanced reporting and aggregation API as well. Documentation for the reporting/aggregation API is beyond the scope of this document, but you should feel free to contact us for further details and a walk-through of this API.

Sample Code

Make sure to visit the ChargeOver GitHub account. Feel free to contact us for additional sample code.

External Keys

ChargeOver has an external keys concept for all objects, to make it easier for you to integrate external systems with ChargeOver. All objects (customers, users, invoices, billing packages, etc.) can be assigned a user-definable, unique external key value. This could be an internal identifier you use to identify a customer, the ID value from some other application, a reference to a primary key within one of your other systems, etc. When making API requests, you can always use the external key value instead of the ChargeOver id value. For example, when creating an invoice you could use the ChargeOver customer_id value:

...
'customer_id': 1234,
...

OR, you could use the external_key value that you defined for that customer:

...
'customer_external_key': 'your custom external key value here',
...

If you have additional questions about this functionality, please contact us for more details.

HTTP Request/Response Codes

The API follows these rules for HTTP requests:

  • If you are creating new objects, use a POST.
  • If you are updating an existing object, use a PUT.
  • If you are trying to get a particular object by id, use a GET.
  • If you are trying to get a list of objects, or query for a list of objects, use a GET.
  • If you are calling an action (e.g. pay an invoice, reset a password, etc.), use a POST.

The API follows these rules for HTTP response codes:

  • If you successfully create an object, you’ll get back a 201 Created HTTP response. You’ll also get back a Location: header with the URL of the new object.
  • If you successfully update an object, you’ll get back a 202 Accepted HTTP response. You’ll also get back a Location: header with the URL of the new object.
  • If you successfully get a specific object, you’ll get back a 200 OK HTTP response.
  • If you try to get a specific object that doesn’t exist, you’ll get back a 404 Not Found HTTP response.
  • If you query for objects, you’ll get back a 200 OK HTTP response.
  • If you successfully call an action, you’ll get back a 200 OK HTTP response.
  • If you do something wrong (e.g. send an invalid JSON request, hit an invalid endpoint, etc.) you will get back a 400 Bad Request HTTP response.
  • If your authentication parameters are incorrect, you will get back a 401 Unauthorized HTTP response.
  • If something goes wrong with ChargeOver itself, you will get back a 500 Internal Server Error HTTP response.

Advanced Flags

ChargeOver supports several advanced usage flags for API requests.

_flag_quickbooks=0

Example:

POST /api/v3/customer?_flag_quickbooks=0

The _flag_quickbooks=0 URL parameter flag disables components of ChargeOver that sync to QuickBooks. For example - normally, if you have ChargeOver connected to QuickBooks, when you create a customer via the API the customer will be pushed to QuickBooks as well. However, if you use the _flag_quickbooks=0 flag when creating the new customer via the API, the push to QuickBooks will be skipped. The customer will be created in ChargeOver like always, but it will not be pushed to QuickBooks. This is sometimes helpful when doing bulk-imports of data that already exists in QuickBooks.

_flag_webhooks=0

Example:

POST /api/v3/customer?flag_webhooks=0

The _flag_webhooks=0 URL parameter flag disables components of ChargeOver that trigger webhooks.

_flag_emails=0

Example:

POST /api/v3/customer?flag_emails=0

The _flag_emails=0 URL parameter flag suppresses sending any outgoing e-mails which ChargeOver would normally send for this action.

_flag_events=0

Documentation needed - coming soon!