Note that Empress support increases the size of the executable by 1MB! If you are not logging to an Empress SQL database Linux won't page in all that unused code so NetCharge's real memory usage would be about 700K.
Since NetCharge logs to databases by clearing house protocol several merchants may wind up in the same database. Since this is an SQL database this is not a problem ie:
-
- If you configure NetCharge to log to a mSQL database you must first create the mSQL database using the msqladmin command. Each protocol you are using will require its own database. ie:
msqladmin create mdi
After creating the mSQL database you should - although it's not *required* - add something like this to your msql.acl file to make it more secure:
(remember, substitute protocol with the protocol you're using)
database = protocol
read=*
write=*
host=your.host.com
access=local
mSQL is simple to use and configure. The mSQL API allows us to add tables so when NetCharge starts up and senses that the 'success' or 'fail' tables aren't there it simply creates them. The process is a lot different with Empress.
-
- With Empress, you must create the database and the tables. Database creation:
empmkdb nabanco
Table creation:
empsql nabanco
Next cut and paste the following two SQL commands into the empsql program and type exit:
CREATE TABLE success (
authorization CHAR(7),
merchant CHAR(32),
date CHAR(12),
time CHAR(12),
product_code int,
keynum LONGINTEGER,
amount CHAR(9),
transaction_code CHAR(3),
transaction_number CHAR(5),
description_code CHAR(5),
card_number CHAR(17),
expiry CHAR(5),
ritid CHAR(16),
ltd CHAR(7),
rrn CHAR(13),
raci CHAR(1),
authsc CHAR(1),
rcc CHAR(3),
vcc CHAR(5),
tsn CHAR(5)
);
CREATE TABLE fail (
merchant CHAR(32),
card_number CHAR(17),
transaction_code CHAR(3),
amount CHAR(9),
expiry CHAR(5),
response CHAR(128),
date CHAR(7),
time CHAR(7),
description_code CHAR(5)
);
is the process id of NetCharge. You find this by doing 'ps ax | grep netcharge'. You will notice more than one netcharge process. Kill the one (sounds nasty, doesn't it?) that has the lowest pid. Do not kill the other ones as the main process - the first process that starts - will signal all of the other netcharge processes to stop.
You have two files to configure: netcharge.conf and syslog.conf. Both are in /etc.
-
- This one requires only one line to be present and it may already be there.
NetCharge logs all output to syslogd, facility LOG_DAEMON, level
LOG_ERR. In order for you to examine NetCharge's error messages you must
ensure that syslogd is configured properly with the line:
daemon.* /var/log/daemon
You may already be logging daemon.* or daemon.err. If so, you can leave things as they are.
If you did add this line to your syslog.conf file, you (as root) must send a HUP signal to your syslogd so it re-reads the config file. ie:
#> ps ax | grep syslogd
47 ? S 0:00 /usr/sbin/syslogd
2683 1 S 0:00 grep syslogd
#> kill -HUP 47
-
- This file contains three sections: global, device,
and merchant. Any text after the '#' character is ignored (comments). While there
can only be one global section, the number of device and merchant
sections can be infinite.
The options are case INsensitive. The values are case sensitive.
-
- All logging is done in this directory. All SQL databases must reside here (except mSQL databases). The <merchant>.<procotol>.{success,error,totals} files, settlement directories, and settlement logs are all stored here.
-
- True or False. If True all transactions are logged to an SQL database the next one or two options are required.
-
- Defines which SQL database NetCharge shall use to
log failed and successful transactions. See the
database section for supported databases and rules
concerning specific SQL databases.
If you are logging to an SQL database, you need to define this.
-
- Only required for mSQL databases. With mSQL, it is
possible to log your transactions to a different
machine over the network. If you do this, you should
send it to a machine behind your corporate firewall
or at least to a trusted network in your building.
-
- Which user ID NetCharge shall run under. Make sure this user can write to the working dir!
-
- Which group ID NetCharge shall run under.
The options are case INsensitive. The values are case sensitive. The xxxx string shall be changed to the merchant name you wish to represent. ie: <Merchant yourcompany>
The mandatory options are: Input Method, Clearing Protocol, and Merchant Number
-
- Used by MDI/GPS only. You will use this when you want to pre-authorize a sale, but not finalize the sale. If you don't finalize the sale, nothing will show up on the card-owner's statement. You do this by initiating an AUTHONLY, and you finalize it with a PREAUTH.
-
- NaBANCO/First Data only. They require that certain packets sent to their mainframes contain this code to determine what category the merchant is in.
-
- In Canada you have one option (tdsi) and in the U.S. you have two (nabanco and mdi). TDSI was bought out by SNS, but the protocol is still the TDSI protocol so we have kept that name. NaBANCO has been bought out by First Data, but First Data has their own protocol so to make sure they know how to set you up, we have kept the NaBANCO protocol name. MDI has been bought out by GPS. To keep things clear we still use the MDI protocol name.
-
- Required by NaBANCO only. They will give you this code.
-
- Right now, the only option is tcp. However, SSL will become available.
-
- Used by TDSI only. Choices are English and French.
-
- Unused right now. Future protocols may use this.
-
- MDI only. Usually a 4 character value determined by GPS.
-
- You will be given a merchant number by your clearing house. This is how the clearing house knows which transactions belong to your company.
-
- NaBANCO only. First Data will give you this value.
-
- NaBANCO only. If you want to process American Express cards, you will have to apply to Amex for a merchant number. Once you have this number, you must inform First Data and set this value to your Amex number.
SNS and GPS note: You need to apply to Amex as well, but you don't have to configure netcharge any differently; you just have to tell the respective clearing house your new merchant number and they'll take care of things for you.
-
- Same as SE.amex, but you apply through diners.
-
- Same as SE.amex, but you apply through discover. Note that SNS does not process discover cards.
-
- Same as SE.amex, but you apply through jcb.
-
- NaBANCO only. Values you can use are 1-99. Designates more than one device per location.
-
- NaBANCO only.
-
- MDI only. Different stores in a chain may want to use this.
-
- Standard ZIP/Postal Code.
The options are case sensitive. The values are case INsensitive. The xxxx string shall be changed to the device name you wish to represent. ie: <device ttyS0>
-
- How long to wait for the modem CONNECT string.
-
- Your modem's INIT string. eg: ATZ
NOTE: This is probably the most important setting! This can cause you lots of frustration when starting up for the first time. NO clearing house supports any error correction, compression, or speed above 2400bps/baud. Don't even think about using a high speed modem without disabling ALL of the mentioned bad features.
-
- Phone number of the clearing house's modems.
-
- Which clearing protocol will this modem handle. You may want to dedicate three modems to one clearing house and two modems to another. You will want to do this if you set up shop as a mall and need to support multiple clearing houses simultaneously.
-
- How many times shall NetCharge redial before giving up on the transaction.
-
- What speed should your modem be set to. ie: 2400
When we say 'settle' we mean two things: 1) when you tell the clearing house that a certain transaction is finalized and 2) the step that a clearing house takes to finalize the processing of the card. At approximately 3:00AM any given clearing house will take all of your settled transactions and start corresponding monetary transactions from the credit card companies into your merchant account. Transactions that haven't been settled will be ignored. Essentially, you settle your credit card transactions with your clearing house and that clearing house settles all of its transactions with the major credit card company.
Some protocols (NaBANCO, TDSI) require settling all of your transactions at once at the end of the day before those clearing houses start the monetary transactions. Other protocols (MDI) settle the transaction the instant you do a SALE or PREAUTH.
In any case, remember that if you are settling as soon as the SALE goes through or at the end of the day, monetary transfers won't occur until early next day. In some cases your bank or clearing house may prepare tapes that get sent to the bank to be processed which will delay your deposit. Also, different clearing houses and credit card institutions hold your money for different periods of time.
In addition to the Standard <Merchant> Settings
Authonly Merchant Number
Store Number
MDI Number
If you are using the MDI protocol you must reference only this section as other protocols can work slightly different.
-
- Authorize a sale, but don't settle it. This allows you to authorize all day long and settle the transactions in one batch using PREAUTH at the end of your day. Dials out to complete transaction.
-
- Process a sale and include street address AVS information. MDI settles the transaction immediately upon completion. Dials out to complete transaction.
-
- Process a sale and include ZIP/Postal code AVS information. MDI settles the transaction immediately upon completion. Dials out to complete transaction.
-
- Process a sale and include ZIP/Postal code and street address AVS information. MDI settles the transaction immediately upon completion. Dials out to complete transaction.
-
- Displays the total sales for a particular card (VISA, MC, etc..) for the current day. Dials out to complete transaction.
-
- The counter-part to AUTHONLY. PREAUTH forces the settlement of the AUTHONLY transaction. Dials out to complete transaction.
-
- Negate a SALE. It is not possible for you to give money to a customer. It is possible to REFUND a previous SALE. Dials out to complete transaction.
-
- Authorize a SALE and settle it. Dials out to complete transaction.
-
- For MDI, this just cleans and backs up the current log files. Dials out to complete transaction.
In addition to the Standard <Merchant> Settings
Qual Code
State Code
Country Code
Category Code
Serial Number
Zip/Postal Code
If you are using the NaBANCO protocol you must reference only this section as other protocols can work slightly different.
-
- Refund money to a customer. No settlement. Does not dial out.
-
- Authorize a SALE but not settle it. Dials out to complete transaction.
-
- Talks to the clearing house and settles every single transaction since the last time you settled. Then if all goes well, the log files will be zeroed and backed up. Dials out to complete transaction.
-
- VOID a transaction. It doesn't matter if the transaction was a REFUND or a SALE, this will ensure this particular transaction is not settled. Does not dial out.
If you are using the TDSI protocol you must reference only this section as other protocols can work slightly different.
-
- Negate a SALE. It is not possible for you to give money to a customer. It is possible to REFUND a previous SALE. No settlement is done.
-
- Authorize a SALE but not settle it.
-
- Talks to the clearing house and settles every single transaction since the last time you settled. Then if all goes well, the log files will be zeroed and backed up.
The interface to the NetCharge API is simple. You only have three function calls! To do a job, you fill out the proper fields in the transaction structure (defined in netc.h) and call netcConnect(), netcTransmit() and netcQuery. After defining these functions and the netc.h structure we will give you a couple of examples to get you started. Keep in mind that full source code has been distributed that shows how to use almost every command (in the utils dir).
-
- SYNOPSIS: Connects to the NetCharge server(host).
If the server is NULL it connects to the local machine using UNIX domain sockets.
If the server is an IP address ie: "207.134.16.1" or a fully qualified domain name ie: "borg.bugless.com" it will use TCP/IP to connect to a NetCharge server on a different machine. People incorporating NetCharge support into their own programs will use this feature. See the Free NetCharge Library Implementation Example for more details on using this remote connectivity feature.
- RETURNS: -1 on error and a NetCharge handle upon success.
-
- SYNOPSIS: Transmits properly filled transaction structure to NetCharge server.
This routine validates all of the structure members it can before sending the data out to the NetCharge server.
NOTE: If the application has already connected to a non-NULL NetCharge server (a NetCharge server on another box) then this routine also connects to BCSI headquarters and logs the transaction attempt. See the Free NetCharge Library Implementation Example for more details on using this remote connectivity feature.
- RETURNS: A response structure. This structure is defined in netc.h. The 'response' member tells us if we've succeeded, failed, or if we've received an Estimated Time of Arrival (ETA) response. The 'data' member gives us a text string reason why we've failed or the (ASCII) time in seconds that the server thinks it will take to process the transaction.
-
- SYNOPSIS: Gets the NetCharge server's response to your query. This is a BLOCKING call. It will wait until either the server sends you a response or the user exits. A user can exit the process by simply clicking the Netscape 'STOP' button or leaving the site by selecting another URL to visit or quit the browser.
- RETURNS: A response structure. Again, defined in netc.h. The 'response' member tells us if we've succeeded or failed. The 'data' member contains a text string explaining why we failed or an approval code upon success.
-
Remember, there are a lot more examples in the utils/ directory!
// gcc saletest.c -I../ -L../lib -lnetcharge -lg++
#include "netc.h"
#include
#include
int main()
{
transaction t;
response r;
int s;
// Fill in the transaction structure.
strcpy(t.merchant, "test");
strcpy(t.cardnum, "1234567890123");
strcpy(t.expiry, "1299");
strcpy(t.amount, "1.00");
t.command = SALE;
// Connects to local NetCharge server
s = netcConnect(NULL);
if (s == -1)
return (-1);
// Transmits the structure
r = netcTransmit(s, &t);
if (r.response == -1) {
printf("\nError: %s\n",r.data);
return (-1);
}
// Wait for the result
r = netcQuery(s);
if (r.response == 0) {
printf("\n%s\n",r.data);
return (0);
}
printf("\n%s\n",r.data);
return (-1);
}
typedef struct transaction {
char merchant[MERCHANTSIZE]; /* which merchant are we processing? */
char command; /* SALE, REFUND, etc.. */
char protocol; /* NETCTEXT, NETCSCRAMBLE, NETCSSL */
char cardnum[CARDSIZE];
char expiry[EXPIRYSIZE]; /* forced MMYY */
char amount[AMOUNTSIZE]; /* 999.50, 0.50, .50, .05 */
/* Note, Library removes '.' internally */
char auth[AUTHSIZE]; /* The saved authorization number */
char operator_id[OPERATORSIZE]; /* For multiple terminals/merchant */
char terminal_id[TERMINALSIZE]; /* Merchant # or Terminal # Internal use */
int product_code; /*Associates product code with transaction*/
char ctype; /* Credit card type. Internal use only */
char referencenum[REFERENCESIZE]; /* For TDSI */
char st_address[ST_ADDRESSSIZE];/* address verification */
char zip[ZIPSIZE]; /* address verification */
char avsop[7]; /* How to handle AVS return codes */
char position[POSITIONSIZE]; /* Position in the success log */
char host_total_level; /* For MDI HOST TOTALS (settlement) */
char from_date[7]; /* MMDDYY for HOST TOTALS */
};
typedef struct response {
char response; // 0,1,2 = Succeded, Failed, ETA response
char data[128];
};
Let's say you (corporation A) are developing an application and you distribute the shareware (limited) version for free over the Internet. When a person (B) wishes to register the software B runs a program (or choses an option) to register the software. A's program will ask B for his card information, place it in a transaction structure and make the three NetCharge library calls. We will assume B has TCP/IP working. The netcConnect() call will connect to A's NetCharge server. The netcTransmit() call will connect and register the transaction with BCSI headquarters so we know to invoice A for an extra 50 cents at the end of the month. Don't worry, all we do is send a large number representing the proper merchant(A), the destination IP address (A's NetCharge server address), the product code, and the command (we only bill A on successful SALE transactions). No confidential information about who the client is, what is being sold for how much, or even card info is sent to us. We just need to know who to bill (A, not B)! Once that is done, the entire transaction structure is sent to A's NetCharge server. A would pre-configure that address into A's application. A's program then calls netcQuery() to get the result. If the result is a successful sale transaction then the libraries contact BCSI headquarters and tell them the transaction was a successful sale. Only when all of this happens successfully do we add 50 cents to A's monthly bill.
Since the above happened successfully, A has B's money, we know to bill A for the use of the library, and B has a registered version of the software. It is now registered because A's software wrote a special key to B's disk that enabled the registered features.
Remember, this system is only used when the libraries to talk to remote NetCharge servers. This should never happen unless you are incorporating NetCharge functionality into custom applications.
-
- Since the user has an easy method of registering the software package, more user's will register. Who want's to take the time out of their day to write a cheque, find an envelope and stamp, and mail the registration? Besides, this doesn't work on an International level because a cheque isn't guaranteed funds. ie: The Canadian Royal Bank may not cash an Australian cheque! Someone from Australia may not even be able to register a Canadian application with an Australian cheque! That is... until NetCharge came along.
More people will register the game than copy it from a friend. If you make it easy to register, people will register! When people want something they want it now. They would register the application/service rather than wait for someone they know to bring the application over so they can copy it.
They would also like to register the application and use the registered features immediately instead of waiting for snail mail delivery of the registered version.
suggestion box
