Skip to main content

JeraSoft Billing Common

The "JeraSoft Billing Common" integration option is designed to expedite the integration process with new equipment. Managed and defined by the JeraSoft team, this option proves particularly valuable for equipment that allows format tuning, such as adjusting columns and order in xDR files or modifying field names in RADIUS packets.

Why choose "JeraSoft Billing Common"?​

  • Rapid integration – if your equipment is not yet listed among the supported options, the "JeraSoft Billing Common" integration provides the quickest path (assuming your equipment allows format tuning, including adjusting columns and order in xDR files or modifying field names in RADIUS packets).
  • Quick solution for historical data upload – If you have historical data that you want to upload to the system as a one-time task, the "JeraSoft Billing Common" format offers a simple and efficient solution.

xDR files​

The file must be in the CSV format, with a comma delimiter and with double quotes in case a comma is used as a value.

Columns​

Columns in the files should be present in the listed order. If any of the columns is not applicable for your use case, just keep it empty.

#FieldDescription
0session_idUnique ID of the session, should be same among multiple events that belong to the same session. For example, if the call has been re-routed, all routing attempts should have same Session ID.
Example: 166qqqb3a-9d9c-4qq8-9252-4a4qqq3b1531
1leg_idUnique ID of the event. For example, if the call has been re-routed, each routing attempt should have unique value.
Example: a9aa9bqq-7dqq-4a1q-aq9q-2d22a0qq55aq
2orig_subscriber_hostOriginator's IP address.
Example: 18.55.67.16
3orig_subscriber_idOriginator's ident name.
Example: user1671
4term_subscriber_hostTerminator's IP address.
Example: 18.55.67.17
5term_subscriber_idTerminator's ident name.
Example: TRUNK-V14
6src_party_id_inSource party ID as received from the originator (for calls – source number).
Example: 00442074865800.
7src_party_id_outSource party ID as sent to the terminator (for calls – source number).
Example: +442074865800.
8src_party_id_billSource party ID translated for billing, only for special cases – typically translation should be done within the billing.
Example: 442074865800.
9dst_party_id_inDestination party ID as received from the originator (for calls – source number).
Example: 00442074865800.
10dst_party_id_outDestination party ID as sent to the terminator (for calls – source number).
Example: +442074865800.
11dst_party_id_billDestination party ID translated for billing, only for special cases – typically translation should be done within the billing.
Example: 442074865800.
12setup_timeSession setup time.
Example: 2012-04-27 12:28:01+00.
13start_timeSession start (connect) time.
Example: 2012-04-27 12:28:06+00.
14stop_timeSession stop (disconnect) time.
Example: 2012-04-27 12:28:56+00.
15volumeConsumed volume (for calls – duration in seconds, for data – volume in bytes, for messages – number of messages, etc).
Example: 50.
16result_codeResult code (according to the table below).
Example: 16.
17pddPost dial delay, in seconds.
Example: 12.1.
18scdSession connection delay, in seconds.
Example: 4.24.
19switch_codeResult code according to equipment table of codes.
Example: 100651.
20orig_bytes_inBytes volume received from the originator.
Example: 6700.
21orig_bytes_outBytes volume sent to the originator.
Example: 8720.
22term_bytes_inBytes volume received from the terminator.
Example: 9182.
23term_bytes_outBytes volume sent to the terminator.
Example: 9214.
24orig_customExtra information for the origination side, will be stored as is.
Example: G711.
25term_customExtra information for the termination side, will be stored as is.
Example: G729.
26services_codeService Ident Code as defined in JeraSoft Billing (for multi-service files only).
Example: calls.
27units_idUnits ID as defined in JeraSoft Billing (for multi-service files only).
Example: sec.
warning

Each field is limited to 255 symbols. Exceeding this limit will result in an error, and the record will be skipped.

Sample records​

Call​

"166qqqb3a-9d9c-4qq8-9252-4a4qqq3b1531","a9aa9bqq-7dqq-4a1q-aq9q-2d22a0qq55aq","18.55.67.16","sofia","19.56.68.17","account_123", "99996477089259","99996477089259","99996477089259","647708925927","647708925927","647708925927","2012-04-27 12:28:01","2012-04-27 12:28:06","2012-04-27 12:28:56","50","16","18","23","1","","","","","G729","G729"
"ddqqqqf3-e095-4qq5-83fa-d919qqqqqqd86","ddqffff3-e095-4qq5-83fa-d919qqffffd86","17.25.67.16","","10.16.17.34","","9821765291", "9821765291","9821765291","99996477201157","99996477201157","99996477201157","2012-06-27 12:28:06","2012-06-27 12:28:06", "2012-06-27 12:28:06","0","17","4","9","1","","","","","G729","g729 g729A g7231 g711A64k g711U64k"

SMS​

"16ou4qb3a-49c9-30c0","","","sofia","","account_123", "","","56","","","93","2018-04-03 14:42:15","","","60","16","","","1","","","","","","","sms",""

Data session​

"0987trdtf-34v9-098f-fhu3y9oh2222","","","sofia","","account_123", "","","1","","","2","2021-08-27 21:20:33","","","10","16","","","1","","","","","","","",""

Result codes​

CodeStatus
16Success
17Busy
31Success
34No channel
200Success
486Busy
503No channel
603Success
987No channel
otherError

RADIUS​

This section describes RADIUS integration between equipment and JeraSoft Billing. It defines full packet flow and the list of fields for each type of the packet. Each part of the flow might be used on its own, meaning that you may use authorization via RADIUS, but do accounting via xDR files.

info

The packets details below include "AVP" flag which stands for Attribute-Value-Pair. When field is marked as AVP it should be sent in Cisco-AVP field in the name=value format.

The "Req" flag means that field is required within each specific type of request. If required field is missing, the whole packet will be skipped.

Authentication​

Authentication request is typically sent when the customer just registers on the equipment and most commonly used for the PBXes or other Class 5 equipment in telephony. This packet may contain Digest authentication information, which will be checked if the user has a password, specified in the billing.

There are 2 possible scenarios how it might be implemented:

  1. User credentials are defined on the equipment and it sends a request just to verify that a user is active in the billing
  2. Equipment does not have any user credentials and always requests authentication to billing to verify user existence

Request packet​

FieldDescriptionAVPReq
request-typeType of the request, must be user.
Example: user
✓✓
src-gw-ipOriginator's IP.
Example: 192.168.0.132
✓✓
src-gw-nameOriginator's ident name.
Example: company-a
✓
[digest]Digest-authorization fields.
Checked only if the account has a password set in the billing.

Response packet​

FieldDescriptionAVP
h323-return-codeQ.931 return code.
Example: 16.
cisco-service-infoJeraSoft return code.
Example: 200.
h323-credit-timeAllowed duration, in seconds.
Example: 3600.
h323-currencyCustomer's currency.
Example: USD.
h323-preferred-langCustomer's preferred language.
Example: en.
subscriberAssigned DIDs.
Example: 442074865800.

Authorization​

Authorization request is typically sent by the equipment when new event is about to happen (call to be placed). Within authorization JeraSoft Billing checks multiple attributes, including status of the customer, its balance, availability of the rate for given destination, etc.

Request packet​

FieldDescriptionAVPReq
request-typeType of the request, must be number.
Example: number.
✓✓
src-gw-ipOriginator's IP.
Example: 192.168.0.132.
✓✓
src-gw-nameOriginator's ident name.
Example: company-a.
✓
[digest]Digest-authorization fields.
Checked only if the account has a password set in the billing.
h323-conf-idUnique ID of the session, should be same among multiple events that belong to the same session. For example, if the call has been re-routed, all routing attempts should have same Session ID.
Example: 166qqqb3a-9d9c-4qq8-9252-4a4qqq3b1531.
✓
h323-call-idUnique ID of the event. For example, if the call has been re-routed, each routing attempt should have unique value.
Example: a9aa9bqq-7dqq-4a1q-aq9q-2d22a0qq55aq.
✓✓
src-number-inSource party ID as received from the originator (for calls – source number).
Example: 0442304770.
✓✓
Calling-Station-IdSource party ID translated for billing, only for special cases – typically translation should be done within the billing.
Example: 442074865800.
dst-number-inDestination party ID as received from the originator (for calls – source number).
Example: 00442074865800.
✓✓
Called-Station-IdDestination party ID translated for billing, only for special cases – typically translation should be done within the billing.
Example: 442074865800.
service-codeService Ident Code as defined in JeraSoft Billing (for multi-service files only).
Example: calls.
✓
unit-idUnits ID as defined in JeraSoft Billing (for multi-service files only).
Example: sec.
✓

Response packet​

FieldDescriptionAVP
h323-return-codeQ.931 return code.
Example: 16.
cisco-service-infoJeraSoft return code.
Example: 200.
h323-credit-timeAllowed duration, in seconds.
Example: 3600.

Accounting Start​

Accounting Start request is typically sent when an event starts (and will last for some time), for example the call is connected. Accounting start requests are used to track list of active session and to check available capacity if any limits are placed.

Request packet​

FieldDescriptionAVPReq
Acct-Status-TypeType of the request, must be Start.
Example: Start.
✓
src-gw-ipOriginator's IP.
Example: 192.168.0.132.
✓✓
src-gw-nameOriginator's ident name.
Example: company-a.
✓
dst-gw-ipTerminator's IP.
Example: 192.168.0.133.
✓✓
dst-gw-nameTerminator's ident name.
Example: company-b.
✓
h323-call-originType of "leg": answer – from customer to equipment, originate – from equipment to vendor.
Example: answer.
✓
h323-conf-idUnique ID of the session, should be same among multiple events that belong to the same session. For example, if the call has been re-routed, all routing attempts should have same Session ID.
Example: 166qqqb3a-9d9c-4qq8-9252-4a4qqq3b1531.
✓
h323-call-idUnique ID of the event. For example, if the call has been re-routed, each routing attempt should have unique value.
Example: a9aa9bqq-7dqq-4a1q-aq9q-2d22a0qq55aq.
✓✓
h323-setup-timeSession setup time.
Example: 2012-04-27 12:28:01+00.
✓
h323-connect-timeSession start (connect) time.
Example: 2012-04-27 12:28:01+00.
✓
src-number-inSource party ID as received from the originator (for calls – source number).
Example: 442074865800.
✓✓
src-number-outSource party ID as sent to the terminator (for calls – source number).
Example: 00442074865800.
✓✓
Calling-Station-IdSource party ID translated for billing, only for special cases – typically translation should be done within the billing.
Example: 442074865800.
dst-number-inDestination party ID as received from the originator (for calls – source number).
Example: =00442074865800.
✓✓
dst-number-outDestination party ID as sent to the terminator (for calls – source number).
Example: 10#442074865800.
✓✓
Called-Station-IdDestination party ID translated for billing, only for special cases – typically translation should be done within the billing.
Example: 442074865800.
service-codeService Ident Code as defined in JeraSoft Billing (for multi-service files only).
Example: calls.
✓
unit-idUnits ID as defined in JeraSoft Billing (for multi-service files only).
Example: sec.
✓

Response packet​

Accounting response is only an acknowledgement of the receipt and doesn't contain any additional fields.

Accounting Stop​

Accounting Stop request is typically sent when an event finishes, for example the call disconnected or message has been sent. It might be sent for both successful and failed attempts in order to track results on the billing side.

Request packet​

FieldDescriptionAVPReq
Acct-Status-TypeType of the request, must be Stop.
Example: Stop.
✓
src-gw-ipOriginator's IP.
Example: 192.168.0.132.
✓✓
src-gw-nameOriginator's ident name.
Example: company-a.
✓
dst-gw-ipTerminator's IP.
Example: 192.168.0.133.
✓✓
dst-gw-nameTerminator's ident name.
Example: company-b.
✓
h323-call-originType of "leg": answer – from customer to equipment, originate – from equipment to vendor.
Example: answer.
✓
h323-conf-idUnique ID of the session, should be same among multiple events that belong to the same session. For example, if the call has been re-routed, all routing attempts should have same Session ID.
Example: 166qqqb3a-9d9c-4qq8-9252-4a4qqq3b1531.
✓
h323-call-idUnique ID of the event. For example, if the call has been re-routed, each routing attempt should have unique value.
Example: a9aa9bqq-7dqq-4a1q-aq9q-2d22a0qq55aq.
✓✓
h323-setup-timeSession setup time.
Example: 2012-04-27 12:28:01+00.
✓
h323-connect-timeSession start (connect) time.
Example: 2012-04-27 12:28:01+00.
✓
h323-disconnect-timeSession stop (disconnect) time.
Example: 2012-04-27 12:28:01+00.
✓
Acct-Session-TimeConsumed volume (for calls – duration in seconds, for data – volume in bytes, for messages – number of messages, etc).
Example: 50.
✓
h323-disconnect-causeQ.931 return code.
Example: 16.
✓
local-disconnect-causeResult code according to equipment table of codes.
Example: 100651.
✓
src-number-inSource party ID as received from the originator (for calls – source number).
Example: 442074865800.
✓✓
src-number-outSource party ID as sent to the terminator (for calls – source number).
Example: 00442074865800.
✓✓
Calling-Station-IdSource party ID translated for billing, only for special cases – typically translation should be done within the billing.
Example: 442074865800.
dst-number-inDestination party ID as received from the originator (for calls – source number).
Example: =00442074865800.
✓✓
dst-number-outDestination party ID as sent to the terminator (for calls – source number).
Example: 10#442074865800.
✓✓
Called-Station-IdDestination party ID translated for billing, only for special cases – typically translation should be done within the billing.
Example: 442074865800.
pdd-timePost dial delay, in seconds.
Example: 12.1.
✓
scd-timeSession connection delay, in seconds.
Example: 4.24.
✓
src-codecOriginator's codec.
Example: G711.
✓
dst-codecTerminator's codec.
Example: G729.
✓
src-bytes-inBytes volume received from the originator.
Example: 6700.
✓
src-bytes-outBytes volume sent to the originator.
Example: 8720.
✓
dst-bytes-inBytes volume received from the terminator.
Example: 9182.
✓
dst-bytes-outBytes volume sent to the terminator.
Example: 9214.
✓
service-codeService Ident Code as defined in JeraSoft Billing (for multi-service files only).
Example: calls.
✓
unit-idUnits ID as defined in JeraSoft Billing (for multi-service files only).
Example: sec.
✓

Response packet​

Accounting response is only an acknowledgement of the receipt and doesn't contain any additional fields.

JeraSoft return codes​

CodeDescription
101Not identified client
111Origination is not allowed for the account
112Client is not active
113Owner of the client is not active
200Successful
201Destination is not allowed for the client
211Destination is blocked for the client
221Insufficient funds
231Destination is not allowed for the owner
232Owner has insufficient funds for the call
301Not enough origination capacity for the call
401No suitable routes found

Q.931 return codes​

CodeDescription
16Successful
21Rejected
34Out of capacity or no routes

External routing​

There are two main approaches to external routing:

  1. Via extended RADIUS field during authorization of the call. This option saves time and traffic as it makes 1 request less.
  2. Via SIP redirect request. This option requires an additional request for routing, but it is a part of the standard SIP protocol.

Routing via RADIUS​

Routing request is completely identical to the Authorization and must be sent to the AUTH port of the RADIUS server. It just asks the billing for a list of possible routes. When equipment receives the list of routes, it should try them one by one until call is successfully connected or last possible route is reached. Empty list might be returned if there are no suitable routes were found.

Request packet​

Routing request should be fully identical to the Authorization request, except the following field:

FieldDescriptionAVPReq
request-typeType of the request, must be route.
Example: route
✓✓

Response packet​

Routing response is fully identical to the Authorization response, except the following field:

FieldDescriptionAVP
Cisco-Control-InfoRoute details (multiple values returned for multiple routes)

Each route details comes in the following format:

<type>/<protocol>/<destination>/<src-number-out>/<dst-number-out>
ParameterDescription
typeIdentification type (one of ip, name)
protocolProtocol (one of sip, h323)
destinationDestination (for ip – IP and port if filled, for name – name)
src-number-outSource party ID as it should be sent to the terminator
dst-number-outDestination party ID as it should be sent to the terminator
Sample response​
ip/sip/192.168.20.7/442074865000/442074865800
ip/sip/192.168.5.77:5080/442074865000/10#442074865800
name/sip/trunk-18/442074865000/442074865800

Routing via SIP redirect​

Routing may be done using SIP Redirect. It works as follows:

  1. After authorization of the event (call), equipment sends INVITE to the SIP redirect server
  2. JeraSoft SIP redirect server looks for possible routes and sends them back in the Contact header with 300 Multiple Choices status.
  3. Equipment tries each of the routes in the given order until the successful connection

To identify a customer, SIP INVITE must contain following fields:

FieldDescription
From, host partOriginator IP
Example: [email protected]
From, user partOriginator Name
Example: user-a@...
INVITE, user partDestination party ID
Example: 442074865000
call-idSession ID
Example: 23bed5361f24bca47dac34f8e9ab64e5