Contraccounts have created this API to enable companies to make use of Contaccounts to its full potential by automating the insertion/creation process on the fly, whatever the company, this PHP based API will allow Contraccounts to abolish the bookkeeping process for any online orders that are sent to us.
The API is constructed to make integration as easy as possible for developers to carry out, this documentation showcases the diversity and power that Contraccounts offers to you as an online seller.
To find out if your server has cURL installed/enabled, please feel free to download our compatibility test file, upload it to your server and execute through a web browser. Get it here: www.contraccounts.com/public_resources/dev_curl_test.zip
Example API request files: www.contraccounts.com/public_resources/api_examples.zip
cURL compatibility test package: www.contraccounts.com/public_resources/dev_curl_test.zip
cURL server source file package: www.contraccounts.com/public_resources/dev_curl.zip
All values are set using the variable name and are separated with an amperstand (&). e.g. (&variable1=value1&variable2=value2)
As you can see its very simple to construct the request, even if you were to programmatically generate the values.
There are 5 types of requests that can be made via this API:
All of these requests have mandatory sub elements that are required to be sent through to complete the request accordingly.
Please note that Income, Expense, Invoice Creation, Refund and Invoice Administration requests can all be called within the same session.
The first variable needs to be your API key, add your API key to the data chain that is going to be sent to Contraccounts:
(example in PHP)
$apidata = "&api_key=APIKEYHERE";
| = Related variables (require eachother to be set in order to fully function) |
Main call initiation variables:
| Variable | Activition Value (required) | Details |
|---|---|---|
| insert_income | TRUE | Initiates an income insertion request. |
| insert_expense | TRUE | Initiates an expense insertion request. |
| create_invoice | TRUE | Initiates an invoice creation request. |
| invoice_admin | TRUE | Initiates an invoice administration request. |
| refund | TRUE | Initiates a refund request. |
insert_income sub-variables:
| Variable | Value Requirements | Details | Requirement |
|---|---|---|---|
| product_id_income | ---- | Product/Service name or ID number. | Mandatory |
| gross_amount_income | Integer or Decimal (2 d.p.) | Total amount of a transaction. |
Mandatory |
| payment_method_income | ---- | Payment method used e.g. cash, cheque, credit card | Mandatory |
| buyer_name_income | ---- | Full name of client/customer | Mandatory |
| custom_income_date | format: yyyy-mm-dd | Set date of payment/insertion. Default: current date | Optional |
| custom_income_id | Under 10 characters | Set a custom reference ID. Required for refunds and admin | Optional |
| quantity_income | Integer | Set a quantity of item(s) involved within transaction. Default: 1 | Optional |
| vat_calculate_income | Decimal | Request Contraccounts to calculate the amount of VAT that was applied to gross amount. Set value as "DEFAULT" if you would like Contraccounts to use the VAT rate stored in the user settings, alternatively set the value as the VAT rate as a decimal. | Optional |
| vat_assign_income | Integer or Decimal (2 d.p.) | Send through the amount of VAT that was applied to the gross amount. (this variable is linked to the variable below) | Optional |
| vat_assign_rate_income | Decimal | Send through the rate at which the VAT was applied (associated with "vat_assign_income"). Set value as "DEFAULT" if you would like Contraccounts to use the VAT rate stored in the user settings. |
Optional |
insert_expense sub-variables:
| Variable | Value Requirements | Details | Requirement |
|---|---|---|---|
| product_id_expense | ---- | Product/Service name or ID number. | Mandatory |
| gross_amount_expense | Integer or Decimal (2 d.p.) | Total amount of a transaction. |
Mandatory |
| payment_method_expense | ---- | Payment method used e.g. cash, cheque, credit card | Mandatory |
| recipient_expense | ---- | Full name of company/recipient | Mandatory |
| custom_expense_date | format: yyyy-mm-dd | Set date of payment/insertion. Default: current date | Optional |
| custom_expense_id | Under 10 characters | Set a custom reference ID. Required for refunds and admin | Optional |
| quantity_expense | Integer | Set a quantity of item(s) involved within transaction. Default: 1 | Optional |
| vat_calculate_expense | Decimal | Request Contraccounts to calculate the amount of VAT that was applied to gross amount. Set value as "DEFAULT" if you would like Contraccounts to use the VAT rate stored in the user settings, alternatively set the value as the VAT rate as a decimal. | Optional |
| vat_assign_expense | Integer or Decimal (2 d.p.) | Send through the amount of VAT that was applied to the gross amount. (this variable is linked to the variable below) | Optional |
| vat_assign_rate_expense | Decimal | Send through the rate at which the VAT was applied (associated with "vat_assign_expense"). Set value as "DEFAULT" if you would like Contraccounts to use the VAT rate stored in the user settings. |
Optional |
create_invoice sub-variables:
| Variable | Value Requirements | Details | Requirement |
|---|---|---|---|
| custom_invoice_id | Under 10 characters | Set a custom reference ID. Required for refunds and admin | Optional |
| service_id_invoice | ---- | Product/Service name or ID number. | Mandatory |
| custom_invoice_date | format: yyyy-mm-dd | Set date of request/creation. Default: current date |
Optional |
| client_invoice | ---- | Full name of company/client/customer | Mandatory |
| address1_invoice | ---- | Address Line 1 of company/client/customer |
Mandatory |
| address2_invoice | ---- | Address Line 2 of company/client/customer | Optional |
| town_invoice | ---- | Town of company/client/customer | Mandatory |
| county_invoice | ---- | County/State of company/client/customer | Mandatory |
| postalcode_invoice | ---- | Postal/Zip Code of company/client/customer | Mandatory |
| country_invoice | ---- | Country of company/client/customer | Mandatory |
| sub_item_1 | ---- | Sub item 1 (item 1) name/service | Mandatory |
| sub_item_1_unitprice | Integer or Decimal (2 d.p.) | Sub item 1 (item 1) price per unit | Mandatory |
| sub_item_1_description | ---- | Sub item 1 (item 1) description | Mandatory |
| sub_item_1_quantity | Integer | Set a quantity of Sub item 1 (item 1). Default: 1 | Optional |
| sub_item_x (up to 12) | ---- | Additonal Sub item (x being the number) name/service | Optional |
| sub_item_x_unitprice | Integer or Decimal (2 d.p.) | Additonal Sub item (x being the number) price per unit | Optional |
| sub_item_x_description | ---- | Additonal Sub item (x being the number) description | Optional |
| sub_item_x_quantity | Integer | Set a quantity of Additonal Sub item (x being the number). Default: 1 | Optional |
| vat_apply_invoice | Decimal | Request Contraccounts to calculate the amount of VAT that was applied and added to the invoice amount. Set value as "DEFAULT" if you would like Contraccounts to use the VAT rate stored in the user settings, alternatively set the value as the VAT rate as a decimal. | Optional |
| vat_assign_invoice | Integer or Decimal (2 d.p.) | Send through the amount of VAT that you would like to add to the invoice. (this variable is linked to the variable below) | Optional |
| vatrate_assign_rate_invoice | Decimal | Send through the rate at which the VAT is to be applied (associated with "vat_assign_invoice"). Set value as "DEFAULT" if you would like Contraccounts to use the VAT rate stored in the user settings. |
Optional |
| client_email | Email Address | Email address of company/client/customer Required for emailing invoice | Optional |
| auto_email_invoice | Boolean (0 OR 1) | Email invoice to customer/company upon creation | Optional |
invoice_admin sub-variables:
| Variable | Value Requirements | Details | Requirement |
|---|---|---|---|
| invoice_reference | ---- | The invoice reference in which you intend to carry out administative tasks | Mandatory |
| invoice_paid | Set as "TRUE" | Set invoice status as "Paid" |
Optional |
| payment_method_invoice | ---- | Payment method used e.g. cash, cheque, credit card |
Optional |
| invoice_paid_date | format: yyyy-mm-dd | Set date of payment. Default: current date (associated with "invoice_paid"). | Optional |
| invoice_awaiting | Set as "TRUE" | Set invoice status as "Awaiting Payment" |
Optional |
| invoice_request_date | format: yyyy-mm-dd | Set date of invoice request. Default: current date (associated with "invoice_awaiting"). | Optional |
| invoice_request_orig | Set as "TRUE" | Keep date of original invoice request. Default: current date (associated with "invoice_awaiting"). | Optional |
| invoice_email | Set as "TRUE" | Email invoice to customer/client (4 emails max. per invoice) |
Optional |
refund sub-variables:
| Variable | Value Requirements | Details | Requirement |
|---|---|---|---|
| refund_reference | ---- | The income reference in which you intend to refund | Mandatory |
| refund_date | format: yyyy-mm-dd | Set date of refund. Default: current date |
Optional |
Scenario: E-commerce software store has just received an order for their latest software suite that has a price of £25.00 plus VAT. The product ID is 12345. John Doe purchased the item via debit card. The store wants to inform Contraccounts that VAT has been applied, and would like Contraccounts to work how much VAT was applied using their account default values.
| $apidata = "&api_key=APIKEYHERE"; $apidata .= "&insert_income=TRUE"; $apidata .= "&product_id_income=12345"; $apidata .= "&gross_amount_income=25.00"; $apidata .= "&payment_method_income=Debit Card"; $apidata .= "&buyer_name_income=John Doe"; $apidata .= "&vat_calculate_income=DEFAULT"; |
// Send through API key to verify ownership of account // Initialise income insertion (prepare Contraccounts for sub variables of insertion) // Set product ID/name // Set gross amount of transaction (includes VAT if applicable) // Specify a payment method // The customer's name // Notify Contraccounts that VAT was applied to this transaction, and want the VAT applied to be calculated using the default rates set in account settings, then insert the VAT income into VAT section of your account. |
This is inserted into the cURL request file (that we provide), illustrated below (datastring is in bold):
<?php //PLEASE INSERT/GENERATE YOUR VARIABLES BETWEEN THE INITIALISATION AND EXECUTION //start//////////////////////////////////////////////////////////////////////////////////////////////////////// $apidata = "&api_key=APIKEYHERE"; //end////////////////////////////////////////////////////////////////////////////////////////////////////////// //DATA IS EXECUTED HERE //please note that a backup system is recommended |
Lets say we wanted to also insert an expense into Contraccounts simultaneously. For example the store has to pay a percentage of royalties to a company called "The Development Team LTD", the amount due is £5.00 and is paid via wire transfer (BACS) on the same day as the sale of the product:
| $apidata = "&api_key=APIKEYHERE"; $apidata .= "&insert_income=TRUE"; $apidata .= "&product_id_income=12345"; $apidata .= "&gross_amount_income=25.00"; $apidata .= "&payment_method_income=Debit Card"; $apidata .= "&buyer_name_income=John Doe"; $apidata .= "&insert_expense=TRUE"; $apidata .= "&product_id_expense=Royalties @ X%"; $apidata .= "&gross_amount_expense=5.00"; $apidata .= "&payment_method_expense=BACS"; $apidata .= "&recipient_expense=The Development Team LTD"; |
// Initialise expense insertion (prepare Contraccounts for sub variables of insertion) // Set expense ID/name // Set gross amount of transaction // Specify a payment method // The recipients' name |
Both an income insertion and an expense insertion will be carried out. This illustrates how easy the integration process really is. Our aim is to make it simple at your end of the process, by placing the sophistication at our end of the process.