CDR Accounting for Cisco IOS Voice Gateways
Debit Card Application
Downloads: This chapterpdf (PDF - 823.0KB) The complete bookPDF (PDF - 2.25MB) | Feedback

Table of Contents

Debit Card Application

Contents

VSA Usage Overview

VSAs in Access Packets

VSAs in Accounting Packets

Programming a RADIUS Server to Use RADIUS Accounting

Debit Card Application VSA Usage: Example

Access Request VSAs from Client to Server

Access Response VSAs From Server to Client

Call Leg 1 Accounting Request VSAs From Client to Server

Call Leg 1 Accounting Response VSAs from RADIUS to Client

Call Leg 2 Accounting Request VSAs from Client to Server

Call Leg 2 Accounting Response VSAs from Server to Client

Call Leg 3 Accounting Request VSAs from Client to Server

Call Leg 3 Accounting Response VSAs from Server to Client

Call Leg 4 Accounting Request VSAs from Client to Server

Call Leg 4 Accounting Response VSAs from Server to Client

Return Codes for Debit Card Applications

Debit Card Application

First Published: February 20, 2001

 

This chapter shows debit card application VSA usage and lists the return codes for debit card applications.

Finding Support Information for Platforms and Cisco IOS and Catalyst OS Software Images

Use Cisco Feature Navigator to find information about platform support and Cisco IOS and Catalyst OS software image support. To access Cisco Feature Navigator, go to http://www.cisco.com/go/cfn . An account on Cisco.com is not required.

VSA Usage Overview

Cisco voice-specific VSAs are included in requests and responses between the voice gateway and the RADIUS server. The gateway, as a RADIUS client, sends and receives VSAs to and from a RADIUS server using a script written in Tool Command Language (Tcl) Interactive Voice Response (IVR).

The Tcl IVR scripts running on the gateway control the use of VSAs between the RADIUS server and the gateway client. By modifying scripts, you can customize the VSAs that are sent from the server to the client or from the client to the server. Tcl IVR scripts can be downloaded from Cisco or you can create your own custom scripts. To download a script, go to the Software Download website at http://www.cisco.com/cgi-bin/tablebuild.pl/tclware . To write your own script or modify an existing script, see the Tcl IVR API Version 2.0 Programmer's Guide.

The following sections describe how RADIUS VSAs are processed in access and accounting packets.

VSAs in Access Packets

The following section describes the VSAs sent by the RADIUS server and the RADIUS client gateway in access packets.

VSAs Sent by RADIUS Client Gateway

The specific set of VSAs sent by the gateway depends on the Tcl IVR script that is running on the gateway and the Cisco IOS release that is installed on the gateway.

VSAs Sent by RADIUS Server

VSAs sent by the RADIUS server to the client are processed by the Cisco IOS software running on the gateway, and the gateway’s behavior (its response to the VSA) is controlled by the Tcl IVR script application that is running (loaded) on the gateway.

VSAs in Accounting Packets

The following section describes the VSAs sent by the RADIUS server and the RADIUS client gateway in accounting packets.

VSAs Sent by RADIUS Client Gateway

The specific set of VSAs sent by the gateway depends on the Tcl IVR script that is running on the gateway and the Cisco IOS release that is installed on the gateway. In Cisco TclWare scripts, different VSAs are included in the Acct_requests for different call legs.


Note For an example of VSAs used on each call leg for the debit-card Tcl IVR script, see the “Debit Card Application VSA Usage: Example” section.


VSAs Sent by RADIUS Server

The RADIUS server must not send any specific Cisco voice VSAs in Acct_responses.

Programming a RADIUS Server to Use RADIUS Accounting

To program a RADIUS server to use specific Cisco voice VSAs, perform the following steps.


Step 1 Create a call flow that describes the behavior of the Cisco voice gateway (RADIUS client).


Note For a sample call flow of the debit card application, see Figure 7.


Step 2 Ensure that the required Cisco IOS release and Tcl IVR scripts are installed and that debugging is enabled. The voice gateway’s behavior varies depending on the Cisco IOS release and Tcl IVR script. The script can either be a Cisco TclWare script or a customized Tcl IVR script.


Note To control the gateway’s behavior by customizing a script, see the Tcl IVR API Version 2.0 Programmer's Guide.


Step 3 Ensure that the voice gateway behavior fits your requirements. For example, you can change the language that the gateway uses for prompts or specify a currency that the gateway must use. You can customize the Tcl IVR script to change the gateway behavior according to your specifications.

Step 4 Create a VSA usage table for the voice gateway (RADIUS client). You can create the VSA usage table directly from the debug logs.


Note For an example, see the “RADIUS Client Debug Log: Example” section.


Step 5 Design your RADIUS server behavior to interoperate with the voice gateway’s VSA usage. The server must accept and process the VSAs that it requires, and send VSAs to the gateway to control the gateway’s behavior.

Step 6 Create the application for your RADIUS server.


 

Figure 7 shows a sample call flow of language selection for the debit card application.

Figure 7 Example of a Call Flow for Debit Card Application

 

Debit Card Application VSA Usage: Example

The following shows an example of how VSAs are used by the Cisco gateway running Cisco IOS Release 12.1(5)T and the Tcl IVR script debitcard 1.1.2.tcl.


Note VSA usage varies based on the Cisco IOS release, Tcl IVR script version, and network configuration. The following tables are based on a PSTN-to-VoIP and VoIP-to-PSTN network.


Table 13 lists the codes used in the tables that follow.

 

Table 13 Table Codes

Code
Description
blank

Not supported in this packet.

0+

Zero or more instances can be used.

0-1

Zero or one instance can be used.

1

Only one instance can be used.

1+

At least one instance must be used, and more instances can be used.

r

Value is readable by Tcl IVR script (getVariable).

s

Can be sent (included in RADIUS packet) by Tcl IVR script (avSend).

Access Request VSAs from Client to Server

Table 14 lists the VSAs that the Cisco gateway (RADIUS client) can send to the billing partner’s server in its RADIUS packets (Access-requests).

You can use the Tcl IVR script running on the gateway to control Cisco RADIUS client usage of VSAs. By modifying the Tcl IVR script, you can cause any of these VSAs to be sent to the server.

 

Table 14 Access Request VSAs from Client to Server

VSAs Sent by Cisco Client on Gateway to Billing Partner’s Server
Tcl
Control?
Access_REQ (code=1) Auth_1
Access_REQ (code =1) Auth_2
Comments

cisco-nas-port (vendortype=2)

h323-billing-model

r

h323-call-origin

h323-call-type

h323-conf-id

1

1

h323-connect-time

h323-credit-amount

r

h323-credit-time

r

h323-currency

h323-disconnect-cause

h323-disconnect-time

h323-gw-id

h323-incoming-conf-id

h323-ivr-in

r

h323-ivr-out

r/s

0+

0+

Present only if avsend is added to the Tcl script.

h323-preferred-lang

r

h323-prompt-id

r

h323-redirect-ip-address

r

h323-redirect-number

r

h323-remote-address

h323-remote-id

Enabled only when you enter the a ttribute h323-remote-id resolved command.

h323-return-code

r

h323-setup-time

h323-time-and-day

r

h323-voice-quality

subscriber

r

0-1

0-1

Only present if you add avsend to the Tcl script.

backward-call-indicators

0-1

0-1

isup-carrier-id

1

1

1

calling-party-category

1

1

1

originating-line-info

1

1

1

charge-number

1

1

1

transmission-medium-req

1

1

1

Access Response VSAs From Server to Client

Table 15 lists the VSAs that the RADIUS server can send to the gateway in its RADIUS packets (Access-responses). The Tcl IVR script running on the gateway controls the gateway’s response to these VSAs.

The RADIUS server can send some of these VSAs to the VoIP gateway without making any changes to the Cisco Tcl IVR debit-card script. Additional Cisco VSAs can be sent by the server to the gateway when customized Tcl IVR scripts are running on the gateway.

You can use the h323-ivr-in VSA to define additional attributes that the RADIUS server sends to the gateway. You can use the h323-ivr-out VSA to define additional attributes that the gateway sends to the RADIUS server.

 

Table 15 Access Response VSAs from RADIUS to Client

VSAs Received by the Cisco Client from the Server
Tcl Control?
Access_Accept (code=2)
Access_Reject (code=3)
Comments
1st
2nd
1st
2nd

cisco-nas-port (vendortype=2)

h323-billing-model

r

0-1

0-1

h323-call-origin

h323-call-type

h323-conf-id

h323-connect-time

h323-credit-amount

r

1

h323-credit-time

r

1

h323-currency

0-1

0-1

h323-disconnect-cause

h323-disconnect-time

h323-gw-id

h323-incoming-conf-id

h323-ivr-in

r

0+

0+

0+

0+

Only processed by the gateway if you add the logic to the Tcl script.

h323-ivr-out

r/s

h323-preferred-lang

r

0-1

0-1

0-1

0-1

h323-prompt-id

r

0-1

0-1

0-1

0-1

h323-redirect-ip-address

r

0-1

0-1

0-1

0-1

h323-redirect-number

r

0-1

0-1

0-1

0-1

h323-remote-address

h323-remote-id

Enabled only when you enter the attribute h323-remote-id resolved command.

h323-return-code

r

0-1

1

1

1

h323-setup-time

h323-time-and-day

r

0-1

h323-voice-quality

subscriber

r

1

1

Call Leg 1 Accounting Request VSAs From Client to Server

Table 16 shows the accounting VSAs sent by the Cisco client to the billing partner’s server for call leg 1.

 

Table 16 Call Leg 1 Accounting Request VSAs from Client to Server

VSAs Sent by Cisco Client Gateway to Billing Partner’s Server
Accting-REQ_start (code=4)
Accting-REQ_stop (code=4)
Comments
Leg 1
Leg 1

acom-level

1

1

backward-call-indicators

0-1

calling-party-category

1

1

charge-number

1

1

charged-units

1

cisco-nas-port (vendortype=2)

1

1

disconnect-text

1

gw-collected-cdn

1

Present only for 2-stage calls (contents same as GwCollectedCalledNumber).

gw-rxd-cdn

1

1

gw-rxd-cgn

1

h323-billing-model

h323-call-origin

1

1

h323-call-type

1

1

h323-conf-id

1

1

h323-connect-time

1

h323-credit-amount

h323-credit-time

h323-currency

h323-disconnect-cause

1

h323-disconnect-time

1

h323-gw-id

0-1

0-1

Value = Gateway configuration.

h323-incoming-conf-id

1

1

h323-ivr-in

h323-ivr-out

0+

0+

Present only if you add avsend to the Tcl script.

h323-preferred-lang

h323-prompt-id

h323-redirect-ip-address

h323-redirect-number

h323-return-code

h323-setup-time

1

1

h323-time-and-day

0-1

Also known as timeAtDest .

h323-voice-quality

1

img-pages-count

1

1

info-type

1

in-intrfc-desc

1

1

in-carrier-id

0–1

Value = Gateway configuration.

in-trunkgroup-label

0–1

Value = Gateway configuration.

isup-carrier-id

1

1

logical-if-index

1

noise-level

1

1

originating-line-info

1

1

peer-address

1

peer-id

1

peer-if-index

1

subscriber

1

1

transmission-medium-req

1

1

tx-duration

1

1

voice-tx-duration

1

1

Call Leg 1 Accounting Response VSAs from RADIUS to Client

The Cisco client on the gateway does not accept VSAs in accounting responses.

Call Leg 2 Accounting Request VSAs from Client to Server

Table 17 lists accounting request VSAs from the Cisco client on the gateway to the billing partner’s server for call leg 2.

 

Table 17 Call Leg 2 Accounting Request VSAs from Client to Server

VSAs Sent by Cisco Client on Gateway to Billing Partner’s Server
Accting-REQ_start (code=4)
Accting-REQ_stop (code=4)
Comments
Leg 2
Leg 2

charged-units

1

cisco-nas-port (vendortype=2)

codec-bytes

1

1

disconnect-text

1

early-packets

1

1

gapfill-with-silence

1

1

gapfill-with-prediction

1

1

gapfill-with-interpolation

1

1

gapfill-with-redundancy

1

1

gk-xlated-cdn

1

Present only if the session target is ‘ras’ (gatekeeper routed calls).

gk-xlated-cgn

1

Present only if the session target is ‘ras’ (gatekeeper routed calls).

gw-final-xlated-cdn

1

The final translated number is the cdn and cgn that eventually goes out of this gateway.

gw-final-xlated-cgn

1

The final translated number is the cdn and cgn that eventually goes out of this gateway.

gw-collected-cdn

1

Pulls this information from the leg 1 record (if present). The contents would be the same as GwCollectedCalledNumber of leg 1.

gw-rxd-cdn

1

1

Pulls this information from the leg 1 record (if present). The contents would be the same as GwReceivedCdn of leg 1.

gw-rxd-cgn

1

Pulls this information from the leg 1 record (if present). The contents would be the same as GwReceivedCgn of leg 1.

h323-billing-model

h323-call-origin

1

1

h323-call-type

1

1

h323-conf-id

1

1

h323-connect-time

1

h323-credit-amount

h323-credit-time

h323-currency

h323-disconnect-cause

1

h323-disconnect-time

1

h323-gw-id

1

1

h323-incoming-conf-id

1

1

h323-ivr-in

h323-ivr-out

0+

0+

Present only if avsend is added to the Tcl script.

h323-preferred-lang

h323-prompt-id

h323-redirect-ip-address

h323-redirect-number

h323-remote-address

1

h323-remote-id

0-1

Enabled only when the attribute h323-remote-id resolved command is entered.

h323-return-code

h323-setup-time

1

1

h323-time-and-day

h323-voice-quality

1

hiwater-playout-delay

1

1

in-carrier-id

0–1

Value = Gateway configuration.

in-trunkgroup-label

0–1

Value = Gateway configuration.

info-type

1

late-packets

1

1

logical-if-index

1

lost-packets

1

1

lowater-playout-delay

1

1

ontime-rv-playout

1

1

out-carrier-id

0–1

Value = Gateway configuration.

out-trunkgroup-label

0–1

Value = Gateway configuration.

outgoing-area

1

1

peer-address

1

peer-id

1

peer-if-index

1

receive-delay

1

1

remote-media-id

Enabled only when you enter the attribute h323-remote-id resolved command.

remote-media-udp-port

1

1

remote-udp-port

1

1

round-trip-delay

1

1

session-protocol

1

1

subscriber

1

1

vad-enable

1

1

Call Leg 2 Accounting Response VSAs from Server to Client

The Cisco client on the gateway does not accept VSAs in accounting responses.

Call Leg 3 Accounting Request VSAs from Client to Server

Table 18 lists the accounting request VSAs from the Cisco client on the gateway to the billing partner’s server for call leg 3.

 

Table 18 Call Leg 3 Accounting Request from Client to Server

VSAs Sent by Cisco Client on Gateway to Billing Partner’s Server
Accting-REQ_start (code=4)
Accting-REQ_stop (code=4)
Comments
Leg 3
Leg 3

charged-units

1

cisco-nas-port (vendortype=2)

codec-bytes

1

1

disconnect-text

1

early-packets

1

1

gapfill-with-silence

1

1

gapfill-with-prediction

1

1

gapfill-with-interpolation

1

1

gapfill-with-redundancy

1

1

gk-xlated-cdn

1

Present only if the session target is ‘ras’ (gatekeeper routed calls).

gk-xlated-cgn

1

Present only if the session target is ‘ras’ (gatekeeper routed calls).

gw-collected-cdn

1

gw-rxd-cdn

1

1

gw-rxd-cgn

1

h323-billing-model

h323-call-origin

1

1

h323-call-type

1

1

h323-conf-id

1

1

h323-connect-time

1

h323-credit-amount

h323-credit-time

h323-currency

h323-disconnect-cause

1

h323-disconnect-time

1

h323-gw-id

0-1

0-1

Value = Gateway configuration.

h323-incoming-conf-id

1

1

h323-ivr-in

h323-ivr-out

0+

0+

Present only if avsend is added to the Tcl script.

h323-preferred-lang

h323-prompt-id

h323-redirect-ip-address

h323-redirect-number

h323-remote-address

h323-remote-id

Enabled only when the attribute h323-remote-id resolved command is entered.

h323-return-code

h323-setup-time

1

1

h323-time-and-day

h323-voice-quality

1

hiwater-playout-delay

1

1

in-carrier-id

0–1

Value = Gateway configuration

incoming-area

1

1

in-trunkgroup-label

0–1

Value = Gateway configuration

info-type

1

late-packets

1

1

logical-if-index

1

lost-packets

1

1

lowater-playout-delay

1

1

ontime-rv-playout

1

1

out-carrier-id

0–1

Value = Gateway configuration.

outgoing-area

1

1

out-trunkgroup-label

0–1

Value = Gateway configuration.

peer-address

1

peer-id

1

peer-if-index

1

remote-media-id

Enabled only when the attribute h323-remote-id resolved command is entered.

receive-delay

1

1

remote-media-udp-port

1

1

remote-udp-port

1

1

round-trip-delay

1

1

session-protocol

1

1

vad-enable

1

1

Call Leg 3 Accounting Response VSAs from Server to Client

The Cisco client on the gateway does not accept VSAs in accounting responses.

Call Leg 4 Accounting Request VSAs from Client to Server

Table 19 lists accounting request VSAs sent by the Cisco client on the gateway to the billing partner’s server for call leg 4.

 

Table 19 Call Leg 4 Accounting Request VSAs Sent from Client to Server

VSAs Sent by Cisco Client on Gateway to Billing Partner’s Server
Accting-REQ_start (code=4)
Accting-REQ_stop (code=4)
Comments
Leg 4
Leg 4

acom-level

1

1

backward-call-indicators

0-1

calling-party-category

charge-number

charged-units

1

cisco-nas-port (vendortype=2)

1

disconnect-text

1

gtd-gw-rxd-cnn

1

gw-collected-cdn

1

Present only for 2 stage calls (contents same as GwCollectedCalledNumber).

gw-final-xlated-cdn

1

gw-final-xlated-cgn

1

The final translated number is the cdn and cgn that eventually goes out of this gateway.

gw-rxd-cdn

1

1

gw-rxd-cgn

1

h323-billing-model

h323-call-origin

1

1

h323-call-type

1

1

h323-conf-id

1

1

h323-connect-time

1

h323-credit-amount

h323-credit-time

h323-currency

h323-disconnect-cause

1

h323-disconnect-time

1

h323-gw-id

0-1

0-1

Value = Gateway configuration.

h323-incoming-conf-id

1

1

h323-ivr-in

h323-ivr-out

0+

0+

Present only if avsend is added to the Tcl script.

h323-preferred-lang

h323-prompt-id

h323-redirect-ip-address

h323-redirect-number

h323-return-code

h323-setup-time

1

1

h323-time-and-day

h323-voice-quality

1

img-pages-count

1

1

in-carrier-id

0–1

Value = Gateway configuration.

in-trunkgroup-label

0–1

Value = Gateway configuration.

info-type

1

isup-carrier-id

noise-level

1

1

originating-line-info

out-intrfc-desc

1

1

out-carrier-id

0–1

Value = Gateway configuration.

out-trunkgroup-label

0–1

Value = Gateway configuration.

peer-address

1

peer-id

1

peer-if-index

1

subscriber

1

1

transmission-medium-req

tx-duration

1

1

voice-tx-duration

1

1

Call Leg 4 Accounting Response VSAs from Server to Client

The Cisco client on the gateway does not accept VSAs in accounting responses.

Return Codes for Debit Card Applications

Return codes are sent by the RADIUS server to the gateway (client) in VSA h323-return-code along with an Access_response_accept or Access_response_reject. For interoperability with Cisco TclWare scripts, the RADIUS server must use an Access_response_accept with return-code zero (success) and an Access_response_reject for all nonzero return-codes.

You can implement new return codes and new gateway behavior by editing the TclWare scripts or writing new Tcl IVR scripts.

Table 20 lists (in numerical order) the predefined return codes that the Cisco gateway and TclWare scripts expect and describes how the debitcard.tcl and app_debitcard.tcl scripts from Cisco handle the return codes.

 

Table 20 Predefined Return Codes for Debit Card Applications

Value
Purpose
When Returned
Tcl Script Instruction to Gateway

0

Success, proceed

If authorization is successful.

Authorization succeeded. Continue with the call.

1

Failed – Invalid Account number

If the first authorization request fails because of an invalid account number.

Authorization failed. Attempt authorization two more times and end the call.

2

Failed – Invalid Password

If the first authorization request fails because of an invalid password.

Authorization failed. Attempt authorization two more times and end the call.

3

Failed – Account in use

After the first authorization request, if there is a second attempt to make a call using the same account. Authorization to use the same account that is already in use fails unless the Internet service provider (ISP) allows multiple users for one account.

Play the account-blocked prompt and end the call.

4

Failed – Zero balance

After the first authorization request.

Play the zero balance prompt and end the call.

5

Failed – Card expired

After the first authorization request when the prepaid calling card date has expired.

Also return this code when the credit card used to pay for the prepaid calling card has expired.

Play the card expired prompt and end the call.

6

Failed – Credit limit

When the account balance has exceeded the credit limit set by the ISP.

Do not proceed with the call. Play the Tcl IVR prompt.

7

Failed – User denied

When the account cannot be authorized for reasons other than the list of possible return codes (described in this table).

Play the destination blocked prompt and end the call.

8

Failed – Service not available

After the second authorization request; for example, the server returns this code if the network is down or if service to a specific calling area is not available.

Do not proceed with the call. Play the Tcl IVR prompt.

9

Failed – Called number blocked

After the second authorization request. This code is used for blocking 900 numbers or for restricting calls to certain area codes.

Play the destination blocked prompt and end the call.

10

Failed – Number of retries exceeded

When the number of times the user attempts to enter the account number and PIN is exceeded.

Do not proceed with the call. Play the Tcl IVR prompt.

11

Failed – Invalid argument

After the first or second authorization requests to provide system-level error information. For example, if the request sent to the RADIUS server is not populated with the correct parameters.

Do not proceed with the call. Play the Tcl IVR prompt.

12

Failed – Insufficient balance

After the first authorization request when the account does not have enough balance to make a call to the destination number entered.

Play insufficient balance message and end the call.

13

Toll-free calls allowed

To allow toll-free (for example, 800 and 888) calls to customer service or operators.

Set the no time limit flag and place the call.

14

Failed – Invalid card number

After the first authorization request.

Do not proceed with the call. Play Tcl IVR prompt.

50

Call is hairpinned back to the PSTN.

When the IP network is not accessible or is busy.

Note Hairpinning allows trunking gateways to route a call back to the PSTN or PBX if the IP network is too busy to handle the call. Hairpinning also can be used to connect the PSTN to the NAS.

Hairpin the call back to the PSTN network.

51

Redirect to called party (use redirect number)

When the call is redirected to the called party using a redirect number.

Redirect the call to a redirect number instead of the requested called number. If an h323-redirect-number VSA is present, the gateway uses it. Otherwise, the call is terminated.

52

Redirect to customer service (use redirect number)

When the call is redirected to customer service.

Set the no time limit flag and place the call to the redirect number. If an h323-redirect-number VSA is also sent, the gateway uses it. Otherwise, the gateway uses its manually configured redirect number.