*************************************************************************** ** COPYRIGHT (c) 2003 BY TRI-8, INCORPORATED. ** ** A L L R I G H T S R E S E R V E D. ** *************************************************************************** OneStep Charge QuickStart Guide ------------------------------- Thank you for your interest in OneStep Charge, the premier electronic payment processing solution for use with the Progress 4GL and other Progress technologies. This QuickStart Guide is intended to help you get OneStep Charge working quickly and completely. The most complete documentation for OSC is found in the User's Guide, but this QuickStart guide should provide you with a basic understanding of OneStep Charge's usage, operation and configuration. Throughout the OneStep Charge documentation set you will find the "$OSC" convention used to refer to the installation directory for OneStep Charge. This basically corresponds to the directory into which you have extracted/ untarred the OSC distribution. For example, if you have untarred your OneStep Charge distribution into /opt on a UNIX machine, $OSC will refer to "/opt/OneStepCharge" for your installation. OneStep Charge Basic Summary: 1. Untar 2. Move 3. Edit 4. Run 5. Profit Sections in this guide ---------------------- 1. Installation [untar, move] 2. Configuration [edit] 3. Basic Usage [run, profit] 4. Diagnostics 5. Getting Help Section 1: Installation ----------------------- The installation of OneStep Charge is very simple and requires only the placement of a few files and, perhaps, the compilation of one of these files. Overview of installation steps: 1. Untar 2. Move Installation steps: 1. Untar/unzip the OneStep Charge distribution file (oscharge_X.Y.src.tar where "X.Y" is the version you are using, such as 1.0). Since you are reading this, chances are you've already completed this step. 2. Move/copy the tri8osc directory into a place included by your PROPATH. Alternatively, you may modify your PROPATH to include the location of your tri8osc directory. PLEASE NOTE THAT COMPILING tri8osc/oscengin.p into a .r should significantly speed up transactions (while you are evaluating OSC), as this will save Progress from having to compile oscengin.p on-the-fly each time you run it (which is very slow). Section 2: Configuration ------------------------ Edit tri8osc/oscapi to configure your OSC installation. This is done by tailoring the assignments to the OSCConfig temp-table to suit your needs. On a basic level, you need merely to specify: 1. Your configuration file location (OSCConfig.confFile). 2. OneStep Charge serial number and license key (OSCConfig.serialNo and OSCConfig.licenseKey). 3. Your OSCBroker connection parameters (OSCConfig.brokerHost, OSCConfig.brokerPort, OSCConfig.username, and OSCConfig.password). The other values that can be set in tri8osc/oscapi can further tailor your installation if you choose to do so. Section 3: Basic Usage ----------------------- Run your transactions/queries through the OneStep Charge Engine nodes via the straightforward OneStep Charge API. This basically involves including a file in your code, creating a temp-table, populating it, and passing it to a run program. Technically speaking, OneStep Charge connects to the OneStep Charge Engine nodes via the OSCBroker, which handles triple-redundant quick failover and 2048-bit encryption for OSC--services not available in the Progress 4GL. A basic diagram of this process, for your information, is: OSC Progress code | ---TCP/IP--> OSCBroker ---TCP/IP w/2048-bit SSL & failover--> OSC Engine nodes The OneStep Charge API is governed by the trExec temp-table. This table is the transport mechanism whereby you can pass information to the OSC Engine and receive results back. The trExec table contains the following fields (data types in parentheses, maximum length/value in brackets where applicable): username (char) password (char) transNo (int) enteredBy (char) [maximum length: 20] trackData (char) cardNo (char) [maximum length: 16] expDate (char) [maximum length: 4] amount (dec) [maximum value: 999999.99] currencyCode (int) CHName (char) [maximum length: 60] CHAddress (char) [maximum length: 80] CHAddress2 (char) [maximum length: 80] CHCity (char) [maximum length: 40] CHState (char) [maximum length: 20] CHZip (char) [maximum length: 20] CHPhone (char) [maximum length: 30] CHEmail (char) [maximum length: 50] AVSResult (int) CVV2 (char) [maximum length: 4] PONo (char) [maximum length: 17] tax (dec) [maximum value: 999999.99] shipToZip (char) [maximum length: 10] vatNo (char) [maximum length: 14] commodityCode (int) [maximum value: 9999] discount (dec) [maximum value: 9999999999.99] shipHandling (dec) [maximum value: 9999999999.99] duty (dec) [maximum value: 9999999999.99] numLines (dec) [maximum value: 99] productCode (char) [maximum length: 20] {EXTENT 99} price (dec) [maximum value: 99999999.99] {EXTENT 99} lineDiscount (dec) [maximum value: 9999999999.99] {EXTENT 99} quantity (int) [maximum value: 999] {EXTENT 99} description (char) [maximum length: 47] {EXTENT 99} uom (char) [maximum length: 12] {EXTENT 99} routingNo (char) [maximum length: 9] accountNo (char) [maximum length: 17] OSCID (char) batchNo (int) authStatus (int) authDetails (char) apprCode (char) authDate (date) authTime (int) settleDate (date) settleTime (int) comment (char) [maximum length: 60] source (char) [maximum length: 40] action (int) timeout (int) qFromDate (date) qFromTime (int) qToDate (date) qToTime (int) However, many of these fields are completely optional for most transaction types. The following fields are required in order to process a credit card authorize-only or authorize-and-settle request, for example: transNo trackdata (if available) cardNo (if no trackdata) expDate (if no trackdata) amount action Providing such information as the cardholder address (CHAddress) for AVS (Address Verification Service) is optional, though it may greatly reduce your processing fees (speaking of credit card transactions), which are levied by the major credit card associations (on behalf of their members) and your merchant account provider. Tri-8-sponsored merchant accounts all take complete advantage of AVS. The possible values for the "action" field are defined in the API interface (tri8osc/oscapi). They are: [CCA stands for Credit Card Action, but it applies to all "card" transactions, including Debit Cards and Private Label Cards, etc.] [ACHA stands for ACH Action] CCA_AUTHONLY (authorize only (pre-authorize)) CCA_PURCHASE (authorize and mark for settlement (purchase/sale)) CCA_CREDIT (credit/return funds to cardholder) CCA_STATUS (check transaction status) CCA_VOICEAUTH (issue a voice/offline authorization) CCA_CAPTURE (mark a pre-authorized (e.g. CCA_AUTHONLY) transaction as ready for settlement) CCA_QTRANS (query OSC Engine for transactions) ACHA_PURCHASE (debit the checking account) ACHA_CREDIT (credit the checking account) ACHA_STATUS (check ACH transaction status) ACHA_QTRANS (query OSC Engine for ACH transactions) The following snippet of code illustrates the authorization of a credit card. In this example, the card is "pre-authorized," which means that an authorization is obtained and the cardholder's open-to-buy limit is reduced, but the transaction will not be settled (captured) until further action is performed at a later time. This might correspond, for example, to order entry time, rather than ship time. ---begin snippet--- {tri8osc/oscapi} create trExec. assign trExec.transNo = next-value(yourProgressSequence) trExec.cardNo = "1234567812345678" trExec.expDate = "0305" trExec.amount = 17.50 trExec.action = CCA_AUTHONLY trExec.timeout = 90. run tri8osc/oscengin.p (input-output table trExec). ---end snippet--- After the run statement returns, you may examine the trExec table to see the results of the transaction. Of particular interest is the authStatus field, which specifies whether or not authorization was obtained (in this example case of a CCA_AUTHONLY action). Possible values for trExec.authStatus are: [CCS stands for Credit Card Status, but it applies to all "card" transactions, including Debit Cards and Private Label Cards, etc.] [ACHS stands for ACH Status] CCS_NODO (nothing has been done--no action executed) CCS_AUTHONLY (transaction has authorized, but is not marked as ready to settle as part of the current settlement batch) CCS_RTS (transaction is authorized and "Ready To Settle" as a part of the currently-building settlement batch) CCS_DECL (transaction has been declined) CCS_CLOSED (transaction has been settled) CCS_ERR (the processor returned an error) CCS_CALL (transaction requires voice authorization) CCS_SYSERR (a system error occurred BEFORE the transaction was submitted, such as a TCP/IP error or connection failure) CCS_SUBERR (a system error occurred AFTER the transaction was submitted, such as a timeout waiting for a response. The transaction must be examined carefully because it LIKELY HAS been sent to the processor and may be charged) ACHS_ACCEPTED (transaction accepted into the ACH network) ACHS_DECLINED (transaction declined and NOT accepted into the network) ACHS_ERR (the processor returned and error) ACHS_SYSERR (same as CCS_SYSERR) ACHS_SUBERR (same as CCS_SUBERR) So, to expand upon the above snippet of code, one might operate using OneStep Charge in the following simple manner. ---begin snippet--- {tri8osc/oscapi} create trExec. assign trExec.transNo = next-value(yourProgressSequence) trExec.cardNo = "1234567812345678" trExec.expDate = "0305" trExec.amount = 17.50 trExec.action = CCA_AUTHONLY trExec.timeout = 90. run tri8osc/oscengin.p (input-output table trExec). find trExec. case trExec.authStatus: when CCS_AUTHONLY then do: message "Card approved: " + trExec.authDetails. /* process order, generate receipt, etc. */ end. /* when CCS_AUTHONLY */ when CCS_DECL then do: message "Card declined: " + trExec.authDetails. /* quit, re-submit a new transaction, etc. */ end. /* when CCS_DECL */ /* etc */ end case. /* trExec.authStatus */ ---end snippet--- If you want to check on the status of a transaction at a later time, you may operate in almost the exact same manner as above, except that you will populate the trExec table with the transNo of a previously-executed transaction and use CCA_STATUS: ---begin snippet--- {tri8osc/oscapi} create trExec. assign trExec.transNo = yourPreviousTransNo trExec.action = CCA_STATUS trExec.timeout = 90. run tri8osc/oscengin.p (input-output table trExec). find trExec. case trExec.authStatus: when CCS_AUTHONLY then do: message "Card approved: " + trExec.authDetails. /* display card details, etc. */ end. /* when CCS_AUTHONLY */ when CCS_DECL then do: message "Card declined: " + trExec.authDetails. /* quit, re-submit a new transaction, etc. */ end. /* when CCS_DECL */ /* etc */ end case. /* trExec.authStatus */ ---end snippet--- This basic structure allows you to perform almost any transaction operation that you could possibly need. Actions such as CCA_CAPTURE, CCA_CREDIT, and the query action CCA_QTRANS are described in the full OneStep Charge User's Guide, as are the trExec.username and trExec.password fields, which are used to facilitate transaction-level multi-merchant support. ACH (e-check) support is also addressed in the User's Guide. For testing purposes, a test credit card number and specific expiration date values can be used. This test credit card number will pass all Luhn validation, but it is not a live account and cannot be used to make actual purchases. Using the expDate along with the test credit card number, you can generate predictable OSC responses for testing purposes. Test credit card information: * card number: 4012888888881 Special predictable "fail" responses: * sending an expDate of 0409 will yield a result of "DECLINED" (CCS_DECL) * sending an expDate of 0509 will yield a result of "CALL" (CCS_CALL) * sending an expDate of 0609 will yield a result of "ERROR" (CCS_ERR, *not* CCS_SYSERR nor CCS_SUBERR) PLEASE NOTE that these predictable responses (using the special expDates above) will be generated by OneStep Charge without sending a transaction to the OSC Engine via the Internet. This means that there won't be any record of the transaction available later for a CCA_STATUS or CCA_QTRANS request. If you would like to generate some predictable responses that DO reside in the OneStep Charge Engine, use the following values, which also include AVS and CVV (CVV2) test values. Note that these values do NOT pass Luhn card number testing, so if you are using such tests in your own code then it will catch these card numbers. Test Cards ---------- (APPROVED (CCS_AUTHONLY, CCS_RTS) and Resident in OSC Engine) Type Number Exp Address City ST Zip CVV -------- ---------------- ----- ------------------ ----------- -- ----- ---- Visa 4111111111111111 04/04 123 Test St. Somewhere CA 90001 123 MC 5411111111111115 04/04 4000 Main St. Anytown AZ 85001 777 AMEX 341111111111111 04/04 12 Colorado Blvd. Elsewhere IL 54321 4000 Discover 6011111111111117 04/04 6789 Green Ave. Nowhere MA 12345 --- Diner's 36484444444446 04/04 7390 Del Mar Blvd. Atown NY 01101 --- JCB 213122222222221 04/04 350 Madison Ave. Springfield OH 40000 --- Test Cards ---------- (DECLINED or CALL (CCS_DECL or CCS_CALL) and Resident in OSC Engine) Number Exp Result ---------------- ----- -------------------------------------- 4012345678909 04/04 General DECLINE (CCS_DECL) 5555444433332226 04/04 Call for Voice Auth (CCS_CALL) 4444111144441111 04/04 General DECLINE/CARD ERROR (CCS_DECL) Some test ACH account numbers can be used in a similar manner to the test credit cards. Like the test cards, one set of test numbers will NOT even be sent to the OSC Engine, so the transaction won't be listed or available for an ACHA_STATUS or ACHA_QTRANS operation, whereas the other number will be sent to the OSC Engine and "faked" there. Test ACH Numbers ---------------- (Response from OneStep Charge without sending to Engine) Routing Number: 789456124 Account Number: 00000 (Response from OneStep Charge Engine and resident there) Routing Number: 789456124 Account Number: 55544433221 For more information on ACH, please see the User's Guide. Now, sit back and profit from real-time payement processing operations in as fast as 1.5 seconds. Take a vacation. Play some golf. Watch an NHL hockey game. RELAX. Section 4: Diagnostics ---------------------- OneStep Charge writes logging information based upon the values of OSCConfig.logMethod and OSCConfig.logSpec. It is highly recommended that you use a logging daemon such as the UNIX syslog to do your logging, in order to handle thousands of virtually simultaneous log messages from many users and sources. To use syslog, one might set OSCConfig as follows: ---begin snippet--- assign OSCConfig.logMethod = "thru" OSCConfig.logSpec = "/usr/bin/logger -p local3.info". ---end snippet--- Alternatively, you may choose to log statically to a file: ---begin snippet--- assign OSCConfig.logMethod = "to" OSCConfig.logSpec = "/var/log/cc.log". ---end snippet--- Occasionally, you may want to obtain more detailed information about the processing of a transaction or the operation of OneStep Charge. This can be done easily by setting the value of OSCConfig.debug to true. Since OneStep Charge supports run-time configuration overriding via the configuration file (specified in OSCConfig.confFile), you can turn on debug information without recompiling anything. Simply set the flag in your configuration file, and the next process to load and run OSC will log more verbosely. Section 5: Getting Help ----------------------- The OneStep Charge documentation set is, of course, the first source for answers to your OSC questions. In addition, please feel free to consult the OneStep Charge website at www.onestepcharge.com, where you'll also find a FAQ section containing answers to some common questions. Email support can be obtained via psupport@onestepcharge.com. If your OneStep Charge license entitles you to phone support, this can be obtained at 405.377.3888 (or check the OneStep Charge website for further/current contact information).