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.
| # | Field | Description |
|---|---|---|
| 0 | session_id | Unique 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 |
| 1 | leg_id | Unique 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 |
| 2 | orig_subscriber_host | Originator's IP address. Example: 18.55.67.16 |
| 3 | orig_subscriber_id | Originator's ident name. Example: user1671 |
| 4 | term_subscriber_host | Terminator's IP address. Example: 18.55.67.17 |
| 5 | term_subscriber_id | Terminator's ident name. Example: TRUNK-V14 |
| 6 | src_party_id_in | Source party ID as received from the originator (for calls – source number). Example: 00442074865800. |
| 7 | src_party_id_out | Source party ID as sent to the terminator (for calls – source number). Example: +442074865800. |
| 8 | src_party_id_bill | Source party ID translated for billing, only for special cases – typically translation should be done within the billing. Example: 442074865800. |
| 9 | dst_party_id_in | Destination party ID as received from the originator (for calls – source number). Example: 00442074865800. |
| 10 | dst_party_id_out | Destination party ID as sent to the terminator (for calls – source number). Example: +442074865800. |
| 11 | dst_party_id_bill | Destination party ID translated for billing, only for special cases – typically translation should be done within the billing. Example: 442074865800. |
| 12 | setup_time | Session setup time. Example: 2012-04-27 12:28:01+00. |
| 13 | start_time | Session start (connect) time. Example: 2012-04-27 12:28:06+00. |
| 14 | stop_time | Session stop (disconnect) time. Example: 2012-04-27 12:28:56+00. |
| 15 | volume | Consumed volume (for calls – duration in seconds, for data – volume in bytes, for messages – number of messages, etc). Example: 50. |
| 16 | result_code | Result code (according to the table below). Example: 16. |
| 17 | pdd | Post dial delay, in seconds. Example: 12.1. |
| 18 | scd | Session connection delay, in seconds. Example: 4.24. |
| 19 | switch_code | Result code according to equipment table of codes. Example: 100651. |
| 20 | orig_bytes_in | Bytes volume received from the originator. Example: 6700. |
| 21 | orig_bytes_out | Bytes volume sent to the originator. Example: 8720. |
| 22 | term_bytes_in | Bytes volume received from the terminator. Example: 9182. |
| 23 | term_bytes_out | Bytes volume sent to the terminator. Example: 9214. |
| 24 | orig_custom | Extra information for the origination side, will be stored as is. Example: G711. |
| 25 | term_custom | Extra information for the termination side, will be stored as is. Example: G729. |
| 26 | services_code | Service Ident Code as defined in JeraSoft Billing (for multi-service files only). Example: calls. |
| 27 | units_id | Units 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
| Code | Status |
|---|---|
| 16 | Success |
| 17 | Busy |
| 31 | Success |
| 34 | No channel |
| 200 | Success |
| 486 | Busy |
| 503 | No channel |
| 603 | Success |
| 987 | No channel |
| other | Error |
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:
- User credentials are defined on the equipment and it sends a request just to verify that a user is active in the billing
- Equipment does not have any user credentials and always requests authentication to billing to verify user existence
Request packet
| Field | Description | AVP | Req |
|---|---|---|---|
| request-type | Type of the request, must be user.Example: user | ✓ | ✓ |
| src-gw-ip | Originator's IP. Example: 192.168.0.132 | ✓ | ✓ |
| src-gw-name | Originator's ident name. Example: company-a | ✓ | |
| [digest] | Digest-authorization fields. Checked only if the account has a password set in the billing. |
Response packet
| Field | Description | AVP |
|---|---|---|
| h323-return-code | Q.931 return code. Example: 16. | |
| cisco-service-info | JeraSoft return code. Example: 200. | |
| h323-credit-time | Allowed duration, in seconds. Example: 3600. | |
| h323-currency | Customer's currency. Example: USD. | |
| h323-preferred-lang | Customer's preferred language. Example: en. | |
| subscriber | Assigned 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
| Field | Description | AVP | Req |
|---|---|---|---|
| request-type | Type of the request, must be number.Example: number. | ✓ | ✓ |
| src-gw-ip | Originator's IP. Example: 192.168.0.132. | ✓ | ✓ |
| src-gw-name | Originator's ident name. Example: company-a. | ✓ | |
| [digest] | Digest-authorization fields. Checked only if the account has a password set in the billing. | ||
| h323-conf-id | Unique 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-id | Unique 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-in | Source party ID as received from the originator (for calls – source number). Example: 0442304770. | ✓ | ✓ |
| Calling-Station-Id | Source party ID translated for billing, only for special cases – typically translation should be done within the billing. Example: 442074865800. | ||
| dst-number-in | Destination party ID as received from the originator (for calls – source number). Example: 00442074865800. | ✓ | ✓ |
| Called-Station-Id | Destination party ID translated for billing, only for special cases – typically translation should be done within the billing. Example: 442074865800. | ||
| service-code | Service Ident Code as defined in JeraSoft Billing (for multi-service files only). Example: calls. | ✓ | |
| unit-id | Units ID as defined in JeraSoft Billing (for multi-service files only). Example: sec. | ✓ |
Response packet
| Field | Description | AVP |
|---|---|---|
| h323-return-code | Q.931 return code. Example: 16. | |
| cisco-service-info | JeraSoft return code. Example: 200. | |
| h323-credit-time | Allowed 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
| Field | Description | AVP | Req |
|---|---|---|---|
| Acct-Status-Type | Type of the request, must be Start.Example: Start. | ✓ | |
| src-gw-ip | Originator's IP. Example: 192.168.0.132. | ✓ | ✓ |
| src-gw-name | Originator's ident name. Example: company-a. | ✓ | |
| dst-gw-ip | Terminator's IP. Example: 192.168.0.133. | ✓ | ✓ |
| dst-gw-name | Terminator's ident name. Example: company-b. | ✓ | |
| h323-call-origin | Type of "leg": answer – from customer to equipment, originate – from equipment to vendor.Example: answer. | ✓ | |
| h323-conf-id | Unique 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-id | Unique 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-time | Session setup time. Example: 2012-04-27 12:28:01+00. | ✓ | |
| h323-connect-time | Session start (connect) time. Example: 2012-04-27 12:28:01+00. | ✓ | |
| src-number-in | Source party ID as received from the originator (for calls – source number). Example: 442074865800. | ✓ | ✓ |
| src-number-out | Source party ID as sent to the terminator (for calls – source number). Example: 00442074865800. | ✓ | ✓ |
| Calling-Station-Id | Source party ID translated for billing, only for special cases – typically translation should be done within the billing. Example: 442074865800. | ||
| dst-number-in | Destination party ID as received from the originator (for calls – source number). Example: =00442074865800. | ✓ | ✓ |
| dst-number-out | Destination party ID as sent to the terminator (for calls – source number). Example: 10#442074865800. | ✓ | ✓ |
| Called-Station-Id | Destination party ID translated for billing, only for special cases – typically translation should be done within the billing. Example: 442074865800. | ||
| service-code | Service Ident Code as defined in JeraSoft Billing (for multi-service files only). Example: calls. | ✓ | |
| unit-id | Units 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
| Field | Description | AVP | Req |
|---|---|---|---|
| Acct-Status-Type | Type of the request, must be Stop.Example: Stop. | ✓ | |
| src-gw-ip | Originator's IP. Example: 192.168.0.132. | ✓ | ✓ |
| src-gw-name | Originator's ident name. Example: company-a. | ✓ | |
| dst-gw-ip | Terminator's IP. Example: 192.168.0.133. | ✓ | ✓ |
| dst-gw-name | Terminator's ident name. Example: company-b. | ✓ | |
| h323-call-origin | Type of "leg": answer – from customer to equipment, originate – from equipment to vendor.Example: answer. | ✓ | |
| h323-conf-id | Unique 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-id | Unique 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-time | Session setup time. Example: 2012-04-27 12:28:01+00. | ✓ | |
| h323-connect-time | Session start (connect) time. Example: 2012-04-27 12:28:01+00. | ✓ | |
| h323-disconnect-time | Session stop (disconnect) time. Example: 2012-04-27 12:28:01+00. | ✓ | |
| Acct-Session-Time | Consumed volume (for calls – duration in seconds, for data – volume in bytes, for messages – number of messages, etc). Example: 50. | ✓ | |
| h323-disconnect-cause | Q.931 return code. Example: 16. | ✓ | |
| local-disconnect-cause | Result code according to equipment table of codes. Example: 100651. | ✓ | |
| src-number-in | Source party ID as received from the originator (for calls – source number). Example: 442074865800. | ✓ | ✓ |
| src-number-out | Source party ID as sent to the terminator (for calls – source number). Example: 00442074865800. | ✓ | ✓ |
| Calling-Station-Id | Source party ID translated for billing, only for special cases – typically translation should be done within the billing. Example: 442074865800. | ||
| dst-number-in | Destination party ID as received from the originator (for calls – source number). Example: =00442074865800. | ✓ | ✓ |
| dst-number-out | Destination party ID as sent to the terminator (for calls – source number). Example: 10#442074865800. | ✓ | ✓ |
| Called-Station-Id | Destination party ID translated for billing, only for special cases – typically translation should be done within the billing. Example: 442074865800. | ||
| pdd-time | Post dial delay, in seconds. Example: 12.1. | ✓ | |
| scd-time | Session connection delay, in seconds. Example: 4.24. | ✓ | |
| src-codec | Originator's codec. Example: G711. | ✓ | |
| dst-codec | Terminator's codec. Example: G729. | ✓ | |
| src-bytes-in | Bytes volume received from the originator. Example: 6700. | ✓ | |
| src-bytes-out | Bytes volume sent to the originator. Example: 8720. | ✓ | |
| dst-bytes-in | Bytes volume received from the terminator. Example: 9182. | ✓ | |
| dst-bytes-out | Bytes volume sent to the terminator. Example: 9214. | ✓ | |
| service-code | Service Ident Code as defined in JeraSoft Billing (for multi-service files only). Example: calls. | ✓ | |
| unit-id | Units 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
| Code | Description |
|---|---|
| 101 | Not identified client |
| 111 | Origination is not allowed for the account |
| 112 | Client is not active |
| 113 | Owner of the client is not active |
| 200 | Successful |
| 201 | Destination is not allowed for the client |
| 211 | Destination is blocked for the client |
| 221 | Insufficient funds |
| 231 | Destination is not allowed for the owner |
| 232 | Owner has insufficient funds for the call |
| 301 | Not enough origination capacity for the call |
| 401 | No suitable routes found |
Q.931 return codes
| Code | Description |
|---|---|
| 16 | Successful |
| 21 | Rejected |
| 34 | Out of capacity or no routes |
External routing
There are two main approaches to external routing:
- Via extended RADIUS field during authorization of the call. This option saves time and traffic as it makes 1 request less.
- 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:
| Field | Description | AVP | Req |
|---|---|---|---|
| request-type | Type of the request, must be route.Example: route | ✓ | ✓ |
Response packet
Routing response is fully identical to the Authorization response, except the following field:
| Field | Description | AVP |
|---|---|---|
| Cisco-Control-Info | Route details (multiple values returned for multiple routes) |
Each route details comes in the following format:
<type>/<protocol>/<destination>/<src-number-out>/<dst-number-out>
| Parameter | Description |
|---|---|
| type | Identification type (one of ip, name) |
| protocol | Protocol (one of sip, h323) |
| destination | Destination (for ip – IP and port if filled, for name – name) |
| src-number-out | Source party ID as it should be sent to the terminator |
| dst-number-out | Destination 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:
- After authorization of the event (call), equipment sends INVITE to the SIP redirect server
- JeraSoft SIP redirect server looks for possible routes and sends them back in the
Contactheader with300 Multiple Choicesstatus. - Equipment tries each of the routes in the given order until the successful connection
To identify a customer, SIP INVITE must contain following fields:
| Field | Description |
|---|---|
| From, host part | Originator IP Example: [email protected] |
| From, user part | Originator Name Example: user-a@... |
| INVITE, user part | Destination party ID Example: 442074865000 |
| call-id | Session ID Example: 23bed5361f24bca47dac34f8e9ab64e5 |