API.TOUCHTOPUP.COM v1.0

Introduction

All responses include a status. Status 0 is indicitive of an error state and is accompanied with a vales for 'msg'.

{ "status": 0, "auth": "false", "msg": "Could not login user with username fred using password supplied" }

When there is no data to return and error response will be returnd

{
	"status": 0,
	"msg": "No Data Available for the parameters you supplied"
}

The API by default returns data as JSON strings. To return XML append /format/xml to the URI.

The API is secured using an api key you must include the following values in the HTTP headers sent to the API

X-API-KEY: Application API Key as supplied by ICRTouch

Methods

The following public methods are available

auth_user

Method: GET

Description:Authenticate the user

Parameters:

username String The users registered email
password String The users password

Returns: user id and customer and company information attached to the user account

Sample request:

http://api.touchtopup.com/index.php/accounts/auth_user/username/someone@example.com/password/mysecretpassword

Sample response: {"status":1,"auth":"true","userid":"1","companies":{"1":{"company_id":"1","customers":["5","10"]},"3":{"company_id":"3","customers":["16"]}}}

company_details

Method: GET

Description: company details

Parameters:

coid Integer The company id

Returns:

Sample request:

http://api.touchtopup.com/index.php/accounts/company_details/cid/1

Sample response: {"status":1,"name":"ICRTouch Testing","db":"10"}

customer_details

Method: GET

Description: customer details

Parameters:

coid Integer The company id
custid Integer The customer id

Returns:

Sample request:

http://api.touchtopup.com/index.php/accounts/customer_details/coid/1/custid/5

Sample response: {"customer":{"TITLE":"Mr","FIRSTNAME":"John","LASTNAME":"Smith","ACCOUNTNUMBER":"54321"},"status":1}

customer_balance

Method: GET

Description: the current balance for a customer

Parameters:

coid Integer The company id
custid Integer The customer id

Returns:

Sample request:

http://api.touchtopup.com/index.php/accounts/customer_balance/coid/1/custid/5

Sample response: {"balance":{"BALANCE":"610","LAST_UPDATE":"2014-05-06 12:44:19"},"status":1}

payment_history

Method: GET

a customers payment history

Parameters:

coid Integer The company id
custid Integer The customer id
limit Integer Optional - Limits the results returned
offset Integer Optional - Limits the results returned
dt_start Date Time Optional - Used in conjunction with dt_end to return data between two dates
dt_end Date Time Optional - Used in conjunction with dt_start to return data between two dates

Returns:

Sample request:

http://api.touchtopup.com/index.php/accounts/payment_history/coid/1/custid/5/

Sample response: {"payments":[{"ADJUSTMENT":"500","SENTTOPOS":"2014-06-16 08:54:07","RECIEVED":"2014-06-16 08:54:06","PAYMENTSOURCE":"1","TRANSACTIONID":"1G653499EP2221416"},{"ADJUSTMENT":"1000","SENTTOPOS":"2014-06-16 08:52:49","RECIEVED":"2014-06-16 08:52:47","PAYMENTSOURCE":"1","TRANSACTIONID":"7D364534GD2849932"},{"ADJUSTMENT":"500","SENTTOPOS":"2014-06-16 08:37:04","RECIEVED":"2014-06-16 08:36:59","PAYMENTSOURCE":"1","TRANSACTIONID":"14P21640DH698105V"},{"ADJUSTMENT":"250","SENTTOPOS":"2014-05-06 11:42:08","RECIEVED":"0000-00-00 00:00:00","PAYMENTSOURCE":"0","TRANSACTIONID":""},{"ADJUSTMENT":"500","SENTTOPOS":"2014-05-06 11:41:10","RECIEVED":"0000-00-00 00:00:00","PAYMENTSOURCE":"0","TRANSACTIONID":""},{"ADJUSTMENT":"100","SENTTOPOS":"2014-05-06 11:21:50","RECIEVED":"0000-00-00 00:00:00","PAYMENTSOURCE":"0","TRANSACTIONID":""},{"ADJUSTMENT":"1000","SENTTOPOS":"2014-05-06 11:12:40","RECIEVED":"0000-00-00 00:00:00","PAYMENTSOURCE":"0","TRANSACTIONID":""},{"ADJUSTMENT":"5000","SENTTOPOS":"2014-05-06 11:11:41","RECIEVED":"0000-00-00 00:00:00","PAYMENTSOURCE":"0","TRANSACTIONID":""},{"ADJUSTMENT":"500","SENTTOPOS":"2014-03-27 16:04:30","RECIEVED":"0000-00-00 00:00:00","PAYMENTSOURCE":"0","TRANSACTIONID":""}],"status":1}

transaction_history

Method: GET

Description: a customers transaction history

Parameters:

coid Integer The company id
custid Integer The customer id
limit Integer Optional - Limits the reseults returned
offset Integer Optional - Used with limit to paginate results
dt_start Date Time Optional - Used in conjunction with dt_end to return data between two dates
dt_end Date Time Optional - Used in conjunction with dt_start to return data between two dates

Returns:

Sample request:

http://api.touchtopup.com/index.php/accounts/transaction_history/coid/1/custid/5

Sample response: {"transactions":[{"HEADERID":"24","SITE":"0","DATE":"0000-00-00","TIME":"00:15:16","SALETOTAL":"995","ACCOUNTADJ":"-995","CONSECNUMBER":"84","SALEID":"1000084","BALANCE":"5905"},{"HEADERID":"23","SITE":"0","DATE":"0000-00-00","TIME":"00:15:13","SALETOTAL":"0","ACCOUNTADJ":"500","CONSECNUMBER":"0","SALEID":"0","BALANCE":"6900"},{"HEADERID":"22","SITE":"0","DATE":"0000-00-00","TIME":"00:15:12","SALETOTAL":"1445","ACCOUNTADJ":"-1445","CONSECNUMBER":"83","SALEID":"1000083","BALANCE":"6400"},{"HEADERID":"21","SITE":"0","DATE":"0000-00-00","TIME":"00:14:59","SALETOTAL":"1575","ACCOUNTADJ":"-1575","CONSECNUMBER":"82","SALEID":"1000082","BALANCE":"7845"},{"HEADERID":"20","SITE":"0","DATE":"0000-00-00","TIME":"00:14:51","SALETOTAL":"400","ACCOUNTADJ":"-400","CONSECNUMBER":"81","SALEID":"1000081","BALANCE":"9420"},{"HEADERID":"19","SITE":"0","DATE":"0000-00-00","TIME":"00:14:47","SALETOTAL":"275","ACCOUNTADJ":"-275","CONSECNUMBER":"80","SALEID":"1000080","BALANCE":"9820"},{"HEADERID":"18","SITE":"0","DATE":"0000-00-00","TIME":"00:14:47","SALETOTAL":"0","ACCOUNTADJ":"10000","CONSECNUMBER":"79","SALEID":"1000079","BALANCE":"10095"},{"HEADERID":"17","SITE":"0","DATE":"0000-00-00","TIME":"00:14:31","SALETOTAL":"195","ACCOUNTADJ":"-195","CONSECNUMBER":"77","SALEID":"1000077","BALANCE":"95"},{"HEADERID":"16","SITE":"0","DATE":"0000-00-00","TIME":"00:14:27","SALETOTAL":"205","ACCOUNTADJ":"0","CONSECNUMBER":"75","SALEID":"1000075","BALANCE":"290"},{"HEADERID":"15","SITE":"0","DATE":"0000-00-00","TIME":"00:14:26","SALETOTAL":"710","ACCOUNTADJ":"-710","CONSECNUMBER":"74","SALEID":"1000074","BALANCE":"290"}],"status":1}

transaction_details

Method:GET

Description: the details of an individual transaction

Parameters:

coid Integer The company id
tid Integer The transaction id

Returns:

Sample request:

http://api.touchtopup.com/index.php/accounts/transaction_detail/tid/67/coid/1

Sample response: {"transaction":{"HEADERID":"67","SITE":"0","DATE":"31032014","TIME":"1039","SALETOTAL":"7","CONSECNUMBER":"0","SALEID":"0","BALANCE":"0","items":[{"ITEMRECORD":"4","QTY":"1","TEXT":"Ale Of Wight "},{"ITEMRECORD":"3","QTY":"1","TEXT":"James"},{"ITEMRECORD":"2","QTY":"1","TEXT":"Ringwood & burg :P"},{"ITEMRECORD":"1","QTY":"1","TEXT":"CARLSBERG"}]},"status":1}

make_payment

Method:GET

Description: Initiates a payement via a 3rd party payment processor (default is PayPal)

Parameters:

coid Integer The company id
custid Integer The customer id
pmtType Integer The Payment service to use (1 => PayPal)
amt Decimal The payment Amount
callback_protocol IntegerThe HTTP protocal to use for callbacks 1=>https 2=>http (Optional default 1)

Returns: In the case of PayPal this function returns the Express Checkout Token that is then passed to paypal when redirecting the customer to PayPal's payment pages

Sample request:

http://api.touchtopup.com/index.php/accounts/make_payment/coid/1/custid/5/pmtType/1/amt/5.00

Sample response: {"response":"EC-1Y43567715771310G","status":1}

record_payment

Method:POST

Description: Finalises a payment via a 3rd party payment processor (default is PayPal) and records the payment in the company/customers ttu_payments table

Parameters:

pmtType Integer The Payment service to use (1 => PayPal)
token String (Paypal) The date time checkout token returned by PayPal. This is used to retrieve the payment details for further processing

Returns: Payment ID from ttu_payments table on success

Sample request:

http://api.touchtopup.com/index.php/accounts/record_payment/pmtType/1/token/EC-1Y43567715771310G

Sample response: {"payment_id":114,"status":1}

user_create

Method:POST

Description: Register a new user account

Parameters:

title String 'Mr','Mrs','Miss','Ms','Master','Rev','Fr','Dr','Prof'
firstname String Required
surname String Required
address_1 String Required (House number/name)
address_2 String
address_3 String
address_4 String
postcode String Required
tel String Required
email String Required Unique
password String Required

Returns: user_id on success

Sample request:

http://api.touchtopup.com/index.php/users/user_create

Sample response: {"status":1,"uid":8}

user_details

Method:GET

Description: Retrieve a users details

Parameters:

uid Integer The user ID of the user to retrieve

Returns:

Sample request:

http://api.touchtopup.com/index.php/users/user_details/uid/1

Sample response: {"status":1,"user":{"title":"Mr","firstname":"John","surname":"Smith","address_1":"26","address_2":"daish way","address_3":"","address_4":"","postcode":"po30 5xb","tel":"08446931119","email":"someone@example.com"}}

user_update

Method:POST

Description: Register a new user account

Parameters:

uid Integer The user ID of the user to update
title String 'Mr','Mrs','Miss','Ms','Master','Rev','Fr','Dr','Prof'
firstname String Required
surname String Required
address_1 String Required (House number/name)
address_2 String
address_3 String
address_4 String
postcode String Required
tel String Required
email String Required Unique

Returns: user_id on success

Sample request:

http://api.touchtopup.com/index.php/users/user_create

Sample response: {"status":1,"user":"1"}

user_change_password

Method:POST

Description: Change a users password

Parameters:

uid Integer The user ID of the user
old_password String Required
new_password String Required

Returns: msg on success

Sample request:

http://api.touchtopup.com/index.php/users/user_change_password

Sample response: {"status":1,"msg":"User password changed"}

user_forgot_password

Method:GET

Description: Retrieves user id if email exists, generates a password reset code, updates database with reset code.

Parameters:

email String The email of the user, Required.

Returns: status, msg, user id, and reset code on success

Sample request:

http://api.touchtopup.com/index.php/users/user_forgot_password/email/user@icrtouch.com

Sample response: {"status":1,"msg":"Email match, User id retrieved, Resetcode generated","userid":"19","resetcode":"4bdd29dbe74db8f969deec72c0f8b651"}

user_check_email_exists

Method:GET

Description: Checks that the provided email exists in ttu_usercredential table in database.

Parameters:

email String The email of the user, Required

Returns: status and msg on success

Sample request:

http://api.touchtopup.com/index.php/users/user_check_email_exists/email/user@icrtouch.com

Sample response: {"status":1,"msg":"Email Found"}

user_check_reset_code

Method:GET

Description: Checks a given resetcode is the same as the resetcode stored in database, for specified user.

Parameters:

userid Integer The user id of the user, Required.
resetcode String The reset code that is attempting to be used by the reset password page, Required.

Returns: status, msg, databaseresetcode on success

Sample request:

http://api.touchtopup.com/index.php/users/user_check_reset_code/userid/19/resetcode/4bdd29dbe74db8f969deec72c0f8b651

Sample response: {"status":1,"msg":"Reset code found","databaseresetcode":"4bdd29dbe74db8f969deec72c0f8b651"}

user_link_account

Method:POST

Description: Link a customer account to a ttu user account

Parameters:

uid IntegerRequired The user ID of the user account
linkkey StringRequired Link key containing company and customer linkinging info (example:000000000001-000000000001-190620141029)

Returns: user_id on success

Sample request:

http://api.touchtopup.com/index.php/users/user_link_account

Sample response: {"status":1,"uid":"7","coid":"1","custid":"1"}

validate_accountkey

Method:GET

Description: Validate the values in an account key

Parameters:

linkkey StringRequired Link key containing company and customer linkinging info (example:000000000001-000000000001-190620141029)

Returns: status and msg on success

Sample request:

http://api.touchtopup.com/index.php/accounts/validate_accountkey/linkkey/000001-000001-463607569

Sample response: {"status":1,"msg":"linkkey is valid"}

customer_wallets

Method:GET

Description: List all wallets the customer is assigned to

Parameters:

coid Integer The company id
cid Integer The customer id

Returns:

Sample request:

http://api.touchtopup.com/index.php/wallets/customer_wallets/coid/1/cid/1

Sample response: { "status": 1, "wallets": [ { "WALLETID": "1", "NAME": "Trip to the museum", "DESCRIPTION": "This wallet is for an event in this case a museum trip. It will not allow you to pay more than the charges set against it.%0AThis event demonstrates how multiple charges can be applied to create a payment plan", "STATUS": "1", "TYPE": "0" }, { "WALLETID": "2", "NAME": "Breakfast club", "DESCRIPTION": "A wallet for a recurring event or activity will have multiple charges made against it and allows the payee to run a positive balance by paying money on at any time", "STATUS": "1", "TYPE": "1" } ] }

customer_wallet_details

Method:GET

Description: The details of a wallet the customer is assigned to

Parameters:

coid Integer The company id
cid Integer The customer id
wallet Integer The wallet id

Returns:

Sample request:

http://api.touchtopup.com/index.php/wallets/customer_wallet_details/coid/1/cid/1/wallet/1

Sample response: { "status": 1, "wallet": { "WALLETID": "1", "NAME": "Trip to the museum", "DESCRIPTION": "This wallet is for an event in this case a museum trip. It will not allow you to pay more than the charges set against it.%0AThis event demonstrates how multiple charges can be applied to create a payment plan", "PAYBYDATE": "2017-09-01", "PURPOSEDATE": "2017-09-30", "STATUS": "1", "ALLOWOVERPAY": "0" }, "payments": [ { "ADJUSTMENT": "500", "RECIEVED": "2017-08-29 12:33:22", "PAYMENTSOURCE": "3", "TRANSACTIONID": "4db477090337098aac47e90196789448", "CHARGEID": "2" }, ... { "ADJUSTMENT": "500", "RECIEVED": "2017-07-20 00:00:00", "PAYMENTSOURCE": "1", "TRANSACTIONID": "ghjfg4565ffty4rh", "CHARGEID": "1" } ], "charges": [ { "ID": "1", "CHARGE": "25.00", "DUEDATE": "2017-07-31" }, { "ID": "2", "CHARGE": "25.00", "DUEDATE": "2017-08-31" }, { "ID": "47", "CHARGE": "10.00", "DUEDATE": "2017-08-29" } ] }

wallet_list

Method:GET

Description: Lists all wallets created by a company

Parameters:

coid Integer The company id

Returns:

Sample request:

http://api.touchtopup.com/index.php/wallets/wallet_list/coid/1

wallet_create

Method:POST

Description: Create a new wallet

Parameters:

coid Integer The company id
name Integer The wallet name
description Integer The wallet description
paybydate Dateoptional
purposedate Dateoptional
status Integer 0-2
allowoverpay boolean 0/1

Returns:

Sample request:

http://api.touchtopup.com/index.php/wallets/wallet_create

Sample response: {"msg":"Wallet created","status":1}

wallet_update

Method:POST

Description: Update an existing wallet

Parameters:

coid Integer The company id
wallet Integer The wallet id
name Integer The wallet name
description Integer The wallet description
paybydate Dateoptional
purposedate Dateoptional
status Integer 0-2
allowoverpay boolean 0/1

Returns:

Sample request:

http://api.touchtopup.com/index.php/wallets/wallet_update

Sample response: {"msg":"Wallet updated","status":1}

wallet_customers_assigned

Method:GET

Description: list all customers assigned to a wallet

Parameters:

coid Integer The company id
wallet Integer The wallet id

Returns:

Sample request:

http://api.touchtopup.com/index.php/wallets/wallet_customers_assigned/coid/1/wallet/1

Sample response: {"customers":[{"NUMBER":"2","ACCOUNTNUMBER":"576576245","LASTNAME":"Bloggs","FIRSTNAME":"Matt","TITLE":"Mr"},{"NUMBER" :"1","ACCOUNTNUMBER":"834523624","LASTNAME":"Evans","FIRSTNAME":"Clive","TITLE":"Mr"},{"NUMBER":"5","ACCOUNTNUMBER":"634643261","LASTNAME":"Gordon","FIRSTNAME":"Darr en","TITLE":"Mr"}],"status":1}

wallet_add_charge

Method:POST

Description: Add a charge to a customers wallet

Parameters:

coid Integer The company id
cid Integer The customer id
wallet Integer The walletid id
amt Decimal(2) The charge amout
duedate Dateoptional

Returns:

Sample request:

http://api.touchtopup.com/index.php/wallets/wallet_add_charge

Sample response: {"customers_charged":["2"],"status":1}

wallet_revoke_charge

Method:POST

Description: remove a charge from a customers wallet

Parameters:

coid Integer The company id
cid Integer The customer id
wallet Integer The wallet id
chargeid Integer The charge id

Returns:

Sample request:

http://api.touchtopup.com/index.php/wallets/wallet_revoke_charge

Sample response: {"msg":"Charge has been removed from Wallet","status":1}

wallet_revoke_charge_from_all

Method:POST

Description: remove a charge from all customers in a wallet

Parameters:

coid Integer The company id
wallet Integer The wallet id
linkid Integer The link id

Returns:

Sample request:

http://api.touchtopup.com/index.php/wallets/wallet_revoke_charge_from_all

Sample response: {"msg":"Charge has been removed from Wallet","status":1}

wallet_add_customer

Method:POST

Description: Assign a customer to a wallet

Parameters:

coid Integer The company id
cid Integer The customer id optional
cgroup Integer The customer group optional
wallet Integer The wallet id

Returns:

Sample request:

http://api.touchtopup.com/index.php/wallets/wallet_add_customer

Sample response: {"customers":2065,"status":1}

wallet_remove_customer

Method:POST

Description: Remove a customer from a wallet

Parameters:

coid Integer The company id
cid Integer The customer id
wallet Integer The wallet id

Returns:

Sample request:

http://api.touchtopup.com/index.php/wallets/wallet_remove_customer

Sample response: {"msg":"Customer has been removed from Wallet","status":1}

Page rendered in 0.0080 seconds