Set-up Instructions : Advanced Level Linking
Our most challenging level of linking for people who want total control.
The customer remains on your website.
Please contact Swreg prior to starting development to confirm you are eligible to use the feature. In addition, study the Intermediate Level as you will need to understand the concepts before proceeding here. This especially applies to multiple products per order.
The Advanced Level principle is that you collect all the order information on your own secure server, you then POST the information to our program called https://usd.swreg.org/cgi-bin/c.cgi that returns a string containing a result code, a currency, type of purchase (i.e., realtime, by fax, by phone, etc), an order number, and a value in your own default currency (See below table for further details). On receipt of that string you will produce a web page for your customer incorporating template web pages stored on our website (you must link to them rather than store them locally as they can change from time to time). Meanwhile we will operate exactly as Basic and Advanced levels in sending out emails, storing transactions, etc.
Result parameters
Key Value Description
result Integer Values/description available below.
ordernumber Integer Swreg order number.
payment_method Integer Swreg Payment Method id (Definitions available at tester.htm).
soft_descriptor Url escaped string For payment method 1 calls. Will return soft descriptor that will appear on credit card statement.
currency Url escaped string Native currency to server/account.
amount Float Amount charged in server/account currency.
txn_currency Url escaped string Transaction currency credit card was charged.
txn_amount Float Amount charged in transaction currency.
Parameters that may be returned by check payment processing
BANKACCOUNTNUMBER String Payment processor customData
BANKNAME String Payment processor customData
BRANCHCODE String Payment processor customData
CHEQUEACCOUNTHOLDER String Payment processor customData
COUNTRYDESCRIPTION String Payment processor customData
PAYMENTREFERENCE String Payment processor customData
POSTALADDRESS1 String Payment processor customData
POSTALADDRESS2 String Payment processor customData
POSTALADDRESS3 String Payment processor customData
SWIFTCODE String Payment processor customData
Parameters that may be returned by electronic/wire payment processing
ACCOUNTHOLDER String Payment processor customData
ADDITIONALBANKINFO String Payment processor customData
ADDITIONALREFERENCE String Payment processor customData
ATTEMPTID String Payment processor customData
BANKACCOUNTNUMBER String Payment processor customData
BANKNAME String Payment processor customData
BANK_SORT_CODE String Payment processor customData
BRANCHCODE String Payment processor customData
CITY String Payment processor customData
COMPLETE_FORMATED_ACCOUNT String Payment processor customData
COUNTRYDESCRIPTION String Payment processor customData
EFFORTID String Payment processor customData
EXTERNALREFERENCE String Payment processor customData
IBAN String Payment processor customData
MERCHANTID String Payment processor customData
ORDERID String Payment processor customData
PAYMENTREFERENCE String Payment processor customData
SPECIALID String Payment processor customData
STATUSDATE String Payment processor customData
STATUSID String Payment processor customData
SWIFTCODE String Payment processor customData
midCategory String Payment processor customData
reference_number String Payment processor customData
Active until October 1st, 2008 (Please discontinue using before this date)
USD Float Amount charged in server/account currency.
GBP Float Amount charged in server/account currency.
EUR Float Amount charged in server/account currency.
CAD Float Amount charged in server/account currency.
??? Float Amount charged but server/account currency unknown.
Please go to a live working site now at http://www.evidence-eliminator.com - this is from our second busiest vendor, Andy Churchill, to whom we are indebted for assistance in developing this system, and is working in anger right now. Feel free to do a test using the "By Phone" or "By Fax" orders but make it clear in your address it is a test purchase so Evidence Eliminator can ignore them in the Pending Orders report. (Of course you could always buy a copy)!! Click here to download Andy's PERL source code for adaption by yourself.
Chris from Cinarsoft has kindly made an adaption to work with PHP. Click here for source code. His website is running it at http://www.cinarsoft.com/
Graham from GPP Software has provided a solution for .NET. Please click here to download. It is written in C# .NET, conversion to VB.NET would be very simple.
Please do not ask these two kind folks to support their code.
You may wish to lift the source code for the list of countries we sell to from https://usd.swreg.org/cgi-bin/s.cgi?s=43387&p=433871&v=0&d=0&q=1&t=
Now look at the web page at http://swreg.org/tester.htm - you will see a test page listing all the variables we need - you should study the code on this page to see how it works. All variables are required to be POSTed but a list of variables that must have data is shown with an asterisk. All variables not required to have a value must still be sent as a null value (this can simply be an = sign like "x=")
What happens when you submit our sample page is that it sends a string to our program at https://usd.swreg.org/cgi-bin/c.cgi
If the order is successful you will get back a zero (0). If the order fails, a non-zero value with be returned. Possible return values are available here.
RULES:
When not a realtime credit card order you need to supply the following web pages in a frame with your pricing confirmation at the top and the following information at the bottom. The information at the top must always quote the Order Number prominently - this is one of the returned values from our server.
* "By Fax" - place http://swreg.org/fax_ordering.htm in the lower frame. Remind people there is a $3 surcharge for ordering this way and that they must use the same email address as already on Paypal or the order will fail.
* "By Phone" - place http://swreg.org/phone_ordering.htm in the lower frame. Remind people there is a $3 surcharge for ordering this way.
* "By Check" or "By Wire" or "By Electronic Funds Transfer" - Remind people there is a $3 surcharge for ordering by check and an $20 surcharge for wire transfer. We will return the information to make the payment in the parameters listed at the top of this page for check or wire payment processing.
* TEST PURCHASES - If the purpose of testing is to test your communications with our server then you can test the results with credit card number 5555555555555555 (5 x 16). You will get a simple page returned with the word "Test Mode" and a list of all variables you have sent. This proves communication with our server. You will not get any transactions logged even in the Pending Orders database, nor any test emails. You can also try using card 36000000000008 which should give you a failure although it should appear as "Test Completed" in the Pending and Failed orders table - if it does show "Test Complete" or "Declined" it proves communication through to our bank. Another way to do an online test is to use the "By Phone" or "By Fax" options. If you wish to test the email layouts then you need to use the Test Order button on each product data entry page online.
* Remember you can select currency and you can select method of payment.
On a multiple product order you only enter the general variables (name, address, etc) once. All transaction variables can be entered just like the Intermediate method described above.
You will need a GetEnv variable to identify the customer's IP - getenv("REMOTE_ADDR") - or try http://www.swreg.org/cgi-bin/whoami.cgi to see how it can work.
Currencies: The best practice is to display and charge your customer in their native currency. You can convert USD to other world currencies by calling http://usd.swreg.org/cgi-bin/rate-calculator.cgi?currency=GBP. Where GBP is the international 3 letter currency code. This will return the conversion rate we are using at that moment so you will need to multiply USD by that rate to get an approximation of what will appear on the customer's credit card. Then you will pass the currency to charge the customer with the c= parameter. We will return the amount and currency of the charge. There are currencies that we do not have exchange rates, the rate calculator will return 0.000000 in these cases.
For a list of supported currencies please visit :-
https://usd.swreg.org/cgi-bin/s.cgi?s=43387&p=433871&v=0&d=0&q=1&t=
MORE RULES:
Please keep an eye on these rules as they may change form time to time until we have worked them all out from experience.
* You must collect IP number (see above)
* You must transmit to us required variables, but you do not need to passed optional variables - see the page at http://swreg.org/tester.htm for a list of required values.
* By "quotation" we mean the display to the customer showing process before the customer commits to final purchase
* You should do the same for VAT if you need it collecting although you should be able to calculate and display this ideally
* Always make clear on the final page after a realtime sale how the charge will appear on their credit card (Use the soft_descriptor parameter passed back from Swreg
* If you receive your own payments from us via BACS or UK cheque the currency value returned by us will be in GBP otherwise USD - ONLY FOR REALTIME TRANSACTIONS - for non-realtime transactions (i.e., by fax) the result will be in USD.
* You can send out a string to our server from a cgi program or directly from a web page. You will always need the response to be sent to a cgi program at your end in order to select the correct response for your customer. If you are using the same cgi program to both send the string and receive the response you do not use the Return Address variable and can leave it set as ra=
* Please make data in the State field compulsory if USA entered as the country.
* Payment options are (1) Realtime credit card (2) By Fax - credit card (3) By Phone - credit card (7) Purchase order by ACH if in USD/CAD, by EFT if in EUR/CAD or by BACS if in GBP. (8) Purchase order by Wire and (9) Purchase order by cheque/check, (10) Purchase order by Local Wire.
* IMPORTANT: In order to send us secure strings you must have LWP (libwww-perl) and Crypt-SSLeay installed in your Perl setup on your server. Ask your ISP to install those modules. These are common modules installed on many servers, it shouldn't cost you anything. It takes a couple of minutes at the ISP.
* How to handle error 21 "Call Authorisation Centre". Please display text similar to that at http://swreg.org/call_auth_centre.htm
* Error 22 comms failure. I suggest thanking them for the order, "there has been a communications problem with their bank but we will try again each hour until completed at which point you will receive an emailed receipt. Please do not attempt to re-order. Any queries please click here but please allow a couple of hours before writing in."
* On your Submit button in giant letters flashing with neon nymphettes please show something like "WARNING: ONLY PRESS ONCE OR YOU MAY BE CHARGED MORE THAN ONCE. IT CAN TAKE UP TO 2 MINUTES TO PROCESS YOUR CARD" In fact it only takes a few seconds but people are impatient and if they click twice the first pipe is broken so even we cannot tell if the card has been charged. This is a classic e-commerce problem. One solution is to issue a serial number with each page that has the final Pay Now button on it. When the page is clicked the serial number is passed back to your cgi that ignores any but the first click.
* Create a system to identify double clicks and ignore them - see the bit about serializing served web pages above paragraph.
* Diner's Club has a 4% surcharge automatically added to the customer's bill due to their higher commission rates.
* SUPPORT: We cannot give programming advice - the samples are to show you how it can be done but that is just one way - you are welcome to adapt the sample code given above - but we are happy to give general implementation advice by clicking here
VAT Issues
You must assume that the local VAT rate will be added to any EU shipping address order - that includes any $3 manual processing fees. You can call a cgi called vnv.cgi to determine the VAT rate. There are some instructions at :-
http://usd.swreg.org/vnv.htm
Please list on the receipt as:
* Price
* VAT @ member state rate
* Total
As part of the address you will need to collect the customer's VAT number. It must be in the format of two letters and a series of numbers (max 15 characters) i.e. GB445812740 in that format. If the customer enters a VAT number, you must pass it to c.cgi in the vn=
If this field is completed, and the customer is not in the EU please make the following information available on the receipt page - and possibly prior to order completion if you feel it may help.
Sold by:
SWREG Inc.
9625 West 76th Street
Eden Prairie, MN 55344
USA
Our VAT Reg. # EU826011714
Your VAT #: FR123456789
"If you are a company within the European Union and did not provide or do not have a VAT number, you can obtain the VAT refund from your taxing authority provided you are VAT exempt. We are unable to refund the VAT tax from a completed order."
A list of country names we accept is available by grabbing the from the following URL :-
https://usd.swreg.org/cgi-bin/s.cgi?s=43387&p=433871&v=0&d=0&q=1&t=
Additional Information
* NEW: Dynamic soft descriptors. We now support dynamic soft descriptors based on the the items the customer ordered. We are passing this information back to you in return query string from the advanced level API. You set the option in the "Author Details." to determine what we should base the soft descriptor on.
* We have added a variable for the 3-number CVV2/CSC field, the number on the back of the credit card. It is 'csc=nnn' (lower case)
* We have updated the variable vt=n to your cgi call to prevent us duplicating orders from yourself. You give each order a unique token up to 30 characters. This will ensure that we will not allow an order to be repeated if we have already logged an order with the same token.
You can also interrogate https://usd.swreg.org/cgi-bin/token2order.pl with three arguments sent as a post (You cannot send as a GET): shop_id (your store number), token_id, and password. The password is specified by you through your author details via the new "Automated calls" password field.
Results are sent as plain text. Each result name/value pair is on its own line: Name/value pairs: StatusCode StatusMessage TokenId OrderId ErrorCode
Here are two call examples: perl and html.
* You can stop people being careless selecting the wrong country with a scroll mouse with the following code:
l
* You can generate printable receipts by following the instructions listed here
* Please have your PayPal customers order using our Intermediate Level as we have too many problems via Advanced Level. Or drop PayPal completely.
* New variable is vp for Variable Pricing. (Gets returned to the keycode generator as pp for price and pv for VAT amount).
* New variable rc for Redemption Code. If 'Merchandising' is enabled for your shop, use this field to pass a Coupon or Promotional URL Code.
No comments:
Post a Comment