Juice Starndard Vending API

Utiliflex uses a set of REST API standards. These standards have the following tenants:

All API's are:

Encrypted (https on a standard (443) or special port)
Uses "basic authentication" as a minimum
Uses a key=value pair request as a GET or POST
Can return XML or JSON
Atomic (One request per API call)
Easy to demonstrate or debug with cURL or a web browser

The actual URL, Login, and Password will vary per Juice systems, for all examples a generic version such as: https://login:password@acme.utiliflex.com/acme/vending2.php is used.

Authentication Test

curl --basic -u login:password -d 'mode=authtest&return=json' \
https://acme.utiliflex.com/acme/vending2.php

{
  "status": "OK",
  "error": 0,
  "message": "auth test and info",
  "login": "betty",
  "name": null,
  "vendornumber": "CEC",
  "balanceowed": null,
  "realaccount": "betty",
  "vendorname": "County Electric",
  "email": "",
  "sms1": "",
  "systemrole": "CSR3",
  "seclevel": "70",
  "vendorgroupowed": "118411.01",
  "vendorgrouplimit": "100000000.00",
  "vendorgroupavailable": 99881588.99,
  "vendorlimit": "20000.00",
  "vendorowed": "2236.00",
  "vendoravailable": 17764
}

The simplest API usage is an authorization test. This works as an excellent example of API usage, and sets the stage for using a web browser, cURL and several programming languages.

HTTP Request

GET https://acme.utiliflex.com/acme/vending2.php?mode=authtest

Available Parameters

The following URL parameters are available when preforming an authtest:

Param	Type	Values	Required	Default
mode	string	authtest	Yes
return	string	json, xml	No	xml

Account Search

curl --basic -u login:password -d 'mode=search&searchfor=00042&return=json' \
https://acme.utiliflex.com/acme/vending2.php

{
  "status": "OK",
  "error": 0,
  "message": "",
  "vendorname": "County Electric",
  "vendornumber": "CEC",
  "email": "",
  "sms1": "",
  "systemrole": "CSR3",
  "seclevel": "70",
  "vendorgroupowed": "118411.01",
  "vendorgrouplimit": "100000000.00",
  "vendorgroupavailable": 99881588.99,
  "vendorlimit": "20000.00",
  "vendorowed": "2236.00",
  "vendoravailable": 17764,
  "s": [
    {
      "portal": "demo",
      "account": "00042",
      "contract": "",
      "name": "Ringo Star",
      "serialnumber": "58759418",
      "address1": "123 Cambleton RD",
      "address2": "",
      "city": "Atlanta",
      "state": "Georgia",
      "sms1": "6034428",
      "email1": ""
    }
  ]
}

Given a string to simple search for, the API will do a search for the meter number, account, external CIS account (cisaccount/contract) and name. It will return a maximum of 20 results in an array/list labeled s.

It is suggested to use this to search for the exact account number or meter serial number and use it for a balance check and then a vend when doing user interfaces for vendors and cashiers.

HTTP Request

GET acme.utiliflex.com/acme/vending2.php?mode=search&searchfor=<string>

Available Parameters

The following URL parameters are available when preforming an account search:

Param	Type	Values	Required	Default
mode	string	search	yes
searchfor	string		yes
return	string	json, xml	no	xml

Balance Inquiry

curl --basic -u login:password -d 'mode=balance&account=00042&return=json' \
https://acme.utiliflex.com/acme/vending2.php

{
  "status": "OK",
  "error": 0,
  "message": "",
  "vendorname": "County Electric",
  "vendornumber": "CEC",
  "email": "",
  "sms1": "6034428",
  "systemrole": "CSR3",
  "seclevel": "70",
  "vendorgroupowed": "118411.01",
  "vendorgrouplimit": "100000000.00",
  "vendorgroupavailable": 99881588.99,
  "vendorlimit": "20000.00",
  "vendorowed": "2236.00",
  "vendoravailable": 17764,
  "motd": "",
  "meterstate": "CONNECT",
  "meterunits": "kWh",
  "com": "Elmar_otv",
  "account": "00042",
  "locid": "L00000038",
  "serialnumber": "58759418",
  "phone2": "",
  "phone1": "4235555555",
  "notifydays": 3,
  "email2": "",
  "email1": "",
  "sms2": "",
  "address1": "123 Cambleton RD",
  "group3": "",
  "group2": "",
  "group1": "",
  "name": "Ringo Star",
  "contract": "",
  "nic": "95460",
  "emailnotify": true,
  "smsnotify": true,
  "phonenotify": true,
  "invto": "Door",
  "portal": "demo",
  "accttype": "PrePaid",
  "locname": "Test loc",
  "loccity": "Atlanta",
  "locaddress2": "",
  "locaddress1": "123 Cambleton RD",
  "days": 3,
  "balancemny": 0.26,
  "balancewh": 29.05,
  "mnyplace": "L",
  "mnysymbol": "$",
  "mnytext": "USD",
  "adumny": 0,
  "tariff": "EASTRIVER",
  "baserate": 9,
  "estremdays": 0,
  "peakusage": 0,
  "aduwh": 0,
  "wallet": 0,
  "gimme5bal": 0,
  "gimme5count": 0,
  "gimme5allowed": true,
  "purchasedkwhthismonth": 0,
  "unitwallet": 29.05,
  "arrearsbalance": 0,
  "recentinvoiceamount": 0,
  "recentinvoicedue": false,
  "recentinvoicedate": "",
  "recentinvoice": false,
  "recentarrearsid": 0,
  "recentinvoicebalance": 0,
  "balance": 0,
  "ststoken": "",
  "amount": 20,
  "type": "cash",
  "transdate": "2017-08-26 04:10:02",
  "transaction": 9980993,
  "purchasedkwh": 1,
  "usagemth": [],
  "usageday": []
}

Preforming a balance check on an account number or meter serial number is a good way to verify if the account or meter exists within Juice. Like other methods in the UtiliSpeak API balance can take either a customer's Juice account number or customer's meter serial number the data returned is the same regardless.

HTTP Request

GET acme.utiliflex.com/acme/vending2.php?mode=balance&account=<string>&serialnumber=<string>

Available Parameters

The following URL parameters are available when preforming a balance inquiry:

Param	Type	Values	Required	Default
mode	string	balance	yes
account	string		no
serialnumber	string		no
return	string	json, xml	no	xml

Last transaction for account/meter by user within the last 24 hours

curl --basic -u login:password -d 'mode=balance&submode=login24&account=00042&return=json' \
https://acme.utiliflex.com/acme/vending2.php

{
  "status": "OK",
  "error": 0,
  "message": "",
  "vendorname": "County Electric",
  "vendornumber": "CEC",
  "email": "",
  "sms1": "6034428",
  "systemrole": "CSR3",
  "seclevel": "70",
  "vendorgroupowed": "118411.01",
  "vendorgrouplimit": "100000000.00",
  "vendorgroupavailable": 99881588.99,
  "vendorlimit": "20000.00",
  "vendorowed": "2236.00",
  "vendoravailable": 17764,
  "motd": "",
  "meterstate": "CONNECT",
  "meterunits": "kWh",
  "com": "Elmar_otv",
  "account": "00042",
  "locid": "L00000038",
  "serialnumber": "58759418",
  "phone2": "",
  "phone1": "4235555555",
  "notifydays": 3,
  "email2": "",
  "email1": "",
  "sms2": "",
  "address1": "123 Cambleton RD",
  "group3": "",
  "group2": "",
  "group1": "",
  "name": "Ringo Star",
  "contract": "",
  "nic": "95460",
  "emailnotify": true,
  "smsnotify": true,
  "phonenotify": true,
  "invto": "Door",
  "portal": "demo",
  "accttype": "PrePaid",
  "locname": "Test loc",
  "loccity": "Atlanta",
  "locaddress2": "",
  "locaddress1": "123 Cambleton RD",
  "days": 3,
  "balancemny": 0.26,
  "balancewh": 29.05,
  "mnyplace": "L",
  "mnysymbol": "$",
  "mnytext": "USD",
  "adumny": 0,
  "tariff": "EASTRIVER",
  "baserate": 9,
  "estremdays": 0,
  "peakusage": 0,
  "aduwh": 0,
  "wallet": 0,
  "gimme5bal": 0,
  "gimme5count": 0,
  "gimme5allowed": true,
  "purchasedkwhthismonth": 0,
  "unitwallet": 29.05,
  "arrearsbalance": 0,
  "recentinvoiceamount": 0,
  "recentinvoicedue": false,
  "recentinvoicedate": "",
  "recentinvoice": false,
  "recentarrearsid": 0,
  "recentinvoicebalance": 0,
  "balance": 0,
  "ststoken": "",
  "amount": 0,
  "type": null,
  "transdate": null,
  "transaction": 0,
  "purchasedkwh": 0,
  "usagemth": [],
  "usageday": []
}

The default balance inquiry will display the most recent transaction from any source. An optional submode=login24 will only display the most recent transaction created by that login in the last 24 hours. If there is none, the transaction values are blank.

HTTP Request

GET acme.utiliflex.com/acme/vending2.php?mode=balance&submode=login24&account=<string>&serialnumber=<string>

Available Parameters

The following URL parameters are available when preforming a balance inquiry:

Param	Type	Values	Required	Default
mode	string	balance	yes
submode	string	login24	yes
account	string		no
serialnumber	string		no
return	string	json, xml	no	xml

Detailed balance information

Can be used for a detailed look at an account and its history. The actual data returned depends on the type of meter. The submode=detail parameter will provide lists/arrays of detailed transactional records and meter reading information.

Available Parameters

The following URL parameters are available when preforming a balance inquiry:

Param	Type	Values	Required	Default
mode	string	balance	yes
submode	string	detail	yes
account	string		no
serialnumber	string		no
return	string	json, xml	no	xml

Vending

Sales Estimate

curl --basic -u login:password -d 'mode=estimate&account=00042&amount=20&return=json' \
https://acme.utiliflex.com/acme/vending2.php

{
  "status": "OK",
  "error": 0,
  "message": "",
  "vendorname": "County Electric",
  "vendornumber": "CEC",
  "email": "",
  "sms1": "6034428",
  "systemrole": "CSR3",
  "seclevel": "70",
  "vendorgroupowed": "118411.01",
  "vendorgrouplimit": "100000000.00",
  "vendorgroupavailable": 99881588.99,
  "vendorlimit": "20000.00",
  "vendorowed": "2236.00",
  "vendoravailable": 17764,
  "motd": "",
  "meterstate": "CONNECT",
  "meterunits": "kWh",
  "com": "Elmar_otv",
  "account": "00042",
  "locid": "L00000038",
  "serialnumber": "58759418",
  "phone2": "",
  "phone1": "4235555555",
  "notifydays": 3,
  "email2": "",
  "email1": "",
  "sms2": "",
  "address1": "123 Cambleton RD",
  "group3": "",
  "group2": "",
  "group1": "",
  "name": "Ringo Star",
  "contract": "",
  "nic": "95460",
  "emailnotify": true,
  "smsnotify": true,
  "phonenotify": true,
  "invto": "Door",
  "portal": "demo",
  "accttype": "PrePaid",
  "locname": "Test loc",
  "loccity": "Atlanta",
  "locaddress2": "",
  "locaddress1": "123 Cambleton RD",
  "days": 3,
  "balancemny": 0.26,
  "balancewh": 29.05,
  "mnyplace": "L",
  "mnysymbol": "$",
  "mnytext": "USD",
  "adumny": 0,
  "tariff": "EASTRIVER",
  "baserate": 9,
  "estremdays": 0,
  "peakusage": 0,
  "aduwh": 0,
  "wallet": 0,
  "gimme5bal": 0,
  "gimme5count": 0,
  "gimme5allowed": true,
  "purchasedkwhthismonth": 0,
  "unitwallet": 29.05,
  "arrearsbalance": 0,
  "recentinvoiceamount": 0,
  "recentinvoicedue": false,
  "recentinvoicedate": "",
  "recentinvoice": false,
  "recentarrearsid": 0,
  "recentinvoicebalance": 0,
  "amount": 20,
  "applytoarrears": 0,
  "applytofixed": 0,
  "applytoservices": 20,
  "applytotaxes": 0.95,
  "applytofuelcharges": 4.01,
  "applytolevycharges": 5.0125,
  "applytolevy2charges": 0,
  "applytowallet": 0,
  "purchasedkwh": 1.0025,
  "kvademandcharge": 0,
  "b1amt": 5.015,
  "b2amt": 0,
  "b3amt": 0,
  "b4amt": 0,
  "b5amt": 0,
  "b6amt": 0,
  "b7amt": 0,
  "b8amt": 0,
  "b9amt": 0,
  "b1wh": 1002.5,
  "b2wh": 0,
  "b3wh": 0,
  "b4wh": 0,
  "b5wh": 0,
  "b6wh": 0,
  "b7wh": 0,
  "b8wh": 0,
  "b9wh": 0,
  "action": "ESTIMATE",
  "transaction": 0
}

To test a transaction without making a sale use mode=estimate and give a transaction amount.

HTTP Request

GET https://acme.utiliflex.com/acme/vending2.php?mode=estimate&submode=<string>&account=<string>&amount=<float>

Available Parameters

The following URL parameters are available when preforming a balance inquiry:

Param	Type	Values	Required	Default
mode	string	estimate	yes
submode	string	wallet, cash, cc, CC, arrears, gimme5	yes
account	string		no
serialnumber	string		no
amount	float		yes
ccauth	string		no
cctrans	string		no
ccnum	string		no
ccexpmth	string		no
ccexpyr	string		no
ccfirst	string		no
cclast	string		no
cczip	string		no
return	string	json, xml	no	xml

If doing a Credit Card sale submode=cc or submode=CC, then the ccauth and cctrans or ccnum, ccexpmth, ccexpyr, ccfirst, ccfirst, cclast, cczip parameters must be present. These fields are used for matching up credit card transactions to an external vendor provided credit card gateway

Vending Type Details

Cash

Setting the submode to cash is the typical use, as it is cash owed to the utiliy. There is no problem in Juice if the actual transaction is a credit card, check, etc.

cc

Setting the submode to cc (note the lower case) is an "outside of Juice" credit card transaction. The internal designation is cash-CC as it is a cash transaction from an external credit card gateway. The optional fields ccauth and cctrans can be used to store some corresponding transaction information in Juice to make it easier to reconcile issues and credit card statements later.

cctrans is usually an incremental transactional referance number and ccauth is often a short alphanumeric string returned by external gateways as proof that the transaction was authorized.

CC

Setting the submode to CC (note upper case) expects the raw credit card information fields to be passed. These fields are ccnum, ccexpmth, ccexpyr, ccfirst, cclast, cczip. This mode will accept that credit card information and process it internally to Juice.

Sales / Vending

curl --basic -u login:password -d 'mode=vend&submode=cash&account=00042&amount=20&return=json' \
https://acme.utiliflex.com/acme/vending2.php

{
  "status": "OK",
  "error": 0,
  "message": "",
  "vendorname": "County Electric",
  "vendornumber": "CEC",
  "email": "",
  "sms1": "6034428",
  "systemrole": "CSR3",
  "seclevel": "70",
  "vendorgroupowed": "118411.01",
  "vendorgrouplimit": "100000000.00",
  "vendorgroupavailable": 99881588.99,
  "vendorlimit": "20000.00",
  "vendorowed": "2236.00",
  "vendoravailable": 17764,
  "motd": "",
  "meterstate": "CONNECT",
  "meterunits": "kWh",
  "com": "Elmar_otv",
  "account": "00042",
  "locid": "L00000038",
  "serialnumber": "58759418",
  "phone2": "",
  "phone1": "4235555555",
  "notifydays": 3,
  "email2": "",
  "email1": "",
  "sms2": "",
  "address1": "123 Cambleton RD",
  "group3": "",
  "group2": "",
  "group1": "",
  "name": "Ringo Star",
  "contract": "",
  "nic": "95460",
  "emailnotify": true,
  "smsnotify": true,
  "phonenotify": true,
  "invto": "Door",
  "portal": "demo",
  "accttype": "PrePaid",
  "locname": "Test loc",
  "loccity": "Atlanta",
  "locaddress2": "",
  "locaddress1": "123 Cambleton RD",
  "days": 3,
  "balancemny": 0.26,
  "balancewh": 29.05,
  "mnyplace": "L",
  "mnysymbol": "$",
  "mnytext": "USD",
  "adumny": 0,
  "tariff": "EASTRIVER",
  "baserate": 9,
  "estremdays": 0,
  "peakusage": 0,
  "aduwh": 0,
  "wallet": 0,
  "gimme5bal": 0,
  "gimme5count": 0,
  "gimme5allowed": true,
  "purchasedkwhthismonth": 0,
  "unitwallet": 30.05,
  "arrearsbalance": 0,
  "recentinvoiceamount": 0,
  "recentinvoicedue": false,
  "recentinvoicedate": "",
  "recentinvoice": false,
  "recentarrearsid": 0,
  "recentinvoicebalance": 0,
  "type": "cash",
  "amount": 20,
  "applytoarrears": "0.00",
  "applytofixed": "0.00",
  "applytoservices": "20.00",
  "applytotaxes": "0.95",
  "applytofuelcharges": "4.01",
  "applytowallet": "0.00",
  "purchasedkwh": 1,
  "kvademandcharge": "0.00",
  "b1amt": "5.01",
  "b2amt": "0.00",
  "b3amt": "0.00",
  "b4amt": "0.00",
  "b5amt": "0.00",
  "b6amt": "0.00",
  "b7amt": "0.00",
  "b8amt": "0.00",
  "b9amt": "0.00",
  "b1wh": "1003",
  "b2wh": "0",
  "b3wh": "0",
  "b4wh": "0",
  "b5wh": "0",
  "b6wh": "0",
  "b7wh": "0",
  "b8wh": "0",
  "b9wh": "0",
  "govnum": "0",
  "action": "SALE",
  "transaction": 9981014,
  "ststoken": ""
}

The most common vending submode is cash as it is cash owed to the utility and the utility does not typically accept the risks associated with the other payment methods used by an external vendor. There are exceptions when the Vending API is used for tight integration with a payment provider that acts as a front end (cashier) for the utility.

HTTP Request

GET https://acme.utiliflex.com/acme/vending2.php?mode=vend&submode=<string>&account=<string>&amount=<float>

Available Parameters

The following URL parameters are available when preforming a balance inquiry:

Param	Type	Values	Required	Default
mode	string	estimate	yes
submode	string	wallet, cash, cc, CC, arrears, gimme5	yes
account	string		no
serialnumber	string		no
amount	float		yes
ccauth	string		no
cctrans	string		no
ccnum	string		no
ccexpmth	string		no
ccexpyr	string		no
ccfirst	string		no
cclast	string		no
cczip	string		no
return	string	json, xml	no	xml
uuid	string		no

Vending Type Details

Cash

Setting the submode to cash is the typical use, as it is cash owed to the utiliy. There is no problem in Juice if the actual transaction is a credit card, check, etc.

cc

cctrans is usually an incremental transactional referance number and ccauth is often a short alphanumeric string returned by external gateways as proof that the transaction was authorized.

CC

Funding a wallet

curl --basic -u login:password -d 'mode=fund&submode=cash&account=00042&amount=20&smsto=1&return=json' \
https://acme.utiliflex.com/acme/vending2.php

{
  "status": "OK",
  "error": 0,
  "message": "",
  "vendorname": "County Electric",
  "vendornumber": "CEC",
  "email": "",
  "sms1": "6034428",
  "systemrole": "CSR3",
  "seclevel": "70",
  "vendorgroupowed": "118431.01",
  "vendorgrouplimit": "100000000.00",
  "vendorgroupavailable": 99881568.99,
  "vendorlimit": "20000.00",
  "vendorowed": "2256.00",
  "vendoravailable": 17744,
  "motd": "",
  "meterstate": "CONNECT",
  "meterunits": "kWh",
  "com": "Elmar_otv",
  "account": "00042",
  "locid": "L00000038",
  "serialnumber": "58759418",
  "phone2": "",
  "phone1": "4235555555",
  "notifydays": 3,
  "email2": "",
  "email1": "",
  "sms2": "",
  "address1": "123 Cambleton RD",
  "group3": "",
  "group2": "",
  "group1": "",
  "name": "Ringo Star",
  "contract": "",
  "nic": "95460",
  "emailnotify": true,
  "smsnotify": true,
  "phonenotify": true,
  "invto": "Door",
  "portal": "demo",
  "accttype": "PrePaid",
  "locname": "Test loc",
  "loccity": "Atlanta",
  "locaddress2": "",
  "locaddress1": "123 Cambleton RD",
  "days": 3,
  "balancemny": 0.27,
  "balancewh": 30.05,
  "mnyplace": "L",
  "mnysymbol": "$",
  "mnytext": "USD",
  "adumny": 0,
  "tariff": "EASTRIVER",
  "baserate": 9,
  "estremdays": 0,
  "peakusage": 0,
  "aduwh": 0,
  "wallet": 0,
  "gimme5bal": 0,
  "gimme5count": 0,
  "gimme5allowed": true,
  "purchasedkwhthismonth": 1,
  "unitwallet": 30.05,
  "arrearsbalance": 0,
  "recentinvoiceamount": 0,
  "recentinvoicedue": false,
  "recentinvoicedate": "",
  "recentinvoice": false,
  "recentarrearsid": 0,
  "recentinvoicebalance": 0,
  "type": "cash",
  "action": "FUND",
  "transaction": 9981015,
  "balance": 20
}

This will put funds into a customers wallet, but not generate a transaction unless the customer has autovend enabled. If they do, that vend is sent via other channels, this function only puts funds into their wallet.

HTTP Request

GET https://acme.utiliflex.com/acme/vending2.php?mode=fund&submode=<string>&account=<string>&amount=<float>

Available Parameters

For a list of available parameters, refer to the list under the Sales Estimate section.

Vend Check

curl --basic -u login:password -d 'mode=vendcheck&uuid=12345&return=json' \
https://acme.utiliflex.com/acme/vending2.php

{
  "uuid": "12345",
  "status": "OK",
  "error": 0,
  "message": "",
  "ststoken": "",
  "amount": 1,
  "type": "cash",
  "transdate": "2019-02-06 09:46:32",
  "transaction": 218,
  "purchasedkwh": 11.3,
  "usagemth": [
    {
      "timestamp": 1548997261,
      "created": "2019-Feb",
      "usagediff": 100000
    }
  ],
  "usageday": [
    {
      "timestamp": 1549602061,
      "timestamp2": "2019-02-08",
      "created": "2019-Feb-08",
      "usagediff": 100000
    }
  ],
  "vendorname": "County Electric",
  "vendornumber": "CEC",
  "email": "",
  "sms1": "",
  "systemrole": "ComMGR",
  "seclevel": "99",
  "vendorgroupowed": "345.00",
  "vendorgrouplimit": "100000000.00",
  "vendorgroupavailable": 99999655,
  "vendorlimit": "10000.00",
  "vendorowed": "345.00",
  "vendoravailable": 9655
}

Vend check allows looking up transaction details for a specific transaction using a 3rd Party Unique ID (often a transaction ID from the 3rd party billing system). This ID must have been provided at the time of the sale using the uuid parameter for this mode to be able to look up the transaction.

HTTP Request

GET https://acme.utiliflex.com/acme/vending2.php?mode=vendcheck

Available Parameters

The URL Parameters avalibale during a vend check are as follows:

Param	Type	Values	Required	Default
mode	string	vendcheck	yes
uuid	string		yes
return	string	json, xml	no	xml

Key / Values to Submit

Key	Values	Description/Comments
mode	authtest, balance, estimate, vend, fund
submode	cash, cc, wallet
return	xml, json, jsonhtml
account	customers account number	in most cases the meter serial number can be used instead
serialnumber	meter serial number	must be unique in this portal
lang	any two character language code	optional, `en` is default, mostly affects error messages
ccauth	credit card auth string	when `submode=cc`
cctrans	credit card transaction number	when `submode=cc`
amount	amount in the local/system currency
pin	customers PIN	Used in unattended payment kiosk situations, must match the customers account password/pin
smsto	Send an SMS receipt (with token if applicable) to either one of the two cellphone numbers on file, or a submitted number	Valid values are `1` or `2` or any valid cellphone number. This value is optional.

Errors

The Juice Vending API uses the following error codes:

Error Code	Meaning
0000	No error, Authentication is OK
1001	Could not locate a matching meter serial number or account
1002	A currency amount is required for this transaction
1003	Amount exceeds gateway single transaction limit
1004	The mode key is not set
1005	The submode is invalid or missing for the mode
1006	Invalid submode for wallet funding
1007	Duplicate POST detected, Resubmit in 2 minutes if valid
1010	Customer not vendible by this means, must see landlord or utility customer service
1099	Transaction Error: (text will vary accordnig to the error, this is a non-API error)
1101	Transaction Error: Credit Card failed either validity or expiration date has failed