What is the API?

The API is a tool for the merchant that needs a custom commerce solution. It is an application programming interface (API) used by merchants to build complex Web sites or other custom systems that process payments. There are also tax and shipping calculators and an Electronic Softgood Download module available for use with the API. The API enables full-featured, highly secure and reliable e-commerce Web sites and custom retail implementations. The API includes LinkPoint Central for comprehensive store management.

Top

How does the API work?

A merchant uses the API software modules to build the payment solution that fits the merchant's unique needs. Modules offered are:

• The payment module
• The shipping calculator module
• The tax calculator module
• The ESD module
• The VirtualCheck module
• The Recurring payments module

Merchants can pick and choose modules as needed. For credit card payments, all of the interactions with credit card processors and financial institutions are resolved and managed through the API payment module. For electronic check payments, all of the interactions with financial institutions are resolved and managed through the API VirtualCheck module.

Once a merchant has integrated the API payment module into a Web site, a customer can purchase items on the merchant's Web site and all payment details are processed automatically. Merchants can then review transaction activity by visiting LinkPoint Central. Let's follow a simple transaction as it travels from the customer's order to approval.

1. A customer selects items for purchase from a merchant's online store over the Internet.
2. The customer clicks on the View Cart button and finalizes the order.
3. The customer clicks on the Check Out button and proceeds to the merchant's payment page.
4. The ordering information is received by the merchant's CSP or by the merchant's own server (self-hosting).
5. The merchant's customized software receives the information, uses the tax and shipping calculators as needed, calculates the order total and passes relevant order and payment information to the API payment module. The API payment module funnels the order data through the secure sockets layer (SSL) pipeline to the LinkPoint Secure Payment Gateway.
6. The LinkPoint Secure Payment Gateway calls and transmits the data through a dedicated, secure frame relay system to the banking network. (Once the transaction is approved and settled, funds are withdrawn from the credit card-issuing bank and deposited into the merchant bank.)
7. A confirmation e-mail is sent to the merchant and the purchaser when the transaction is completed.
8. The merchant's Web server receives the transaction response information. This generally happens within six seconds.
9. The merchant's Web server displays the transaction results to the customer.
10. The merchant uses LinkPoint Central reports to review transactions and mark items as shipped (e.g., ready for settlement).

Top

What security measures are used?

The Gateway provides data encryption, server authentication, message integrity and optional client authentication for a TCP/IP connection by the Secure Sockets Layer (SSL) protocol. SSL is a protocol developed by Netscape® to provide secure transmission of private information that is sent over the Internet. This protocol uses public and private key pairs to encrypt data. The public and private keys are dissimilar and each pair is unique; therefore, the keys possessed verify the sender's identity. The public key is distributed to the merchant, ISP or CSP in the form of a digital certificate, which contains information that can verify the key holder identity and the key validity. The private key is kept confidential and remains on the Payment Gateway. If data is encrypted with the private key, only the public key can decrypt it. If data is encrypted with the public key, only the private key can decrypt it. This process prevents the data from being compromised while in transit.

Top

What do I need to know to use the API?

You need to have some programming skills to use the API. Any of the following languages can be used to invoke the API:

• C/C++
• C#
• ASP, Visual Basic, or VBScript
• PERL
• PHP
• .Net
• XML
• Java^TM

Top

How do I get the API and/or wrapper software?

All the LinkPoint software and related documentation is downloadable from the downloads section of http://www.LinkPoint.com. You will need a live merchant account with a LinkPoint-compatible merchant service provider or a LinkPoint test account before you can use the LinkPoint software.

Top

Do you offer a Software Development Kit (SDK)?

We do not offer SDKs, but we offer the software modules in many different programming languages.

Top

What fraud protection measures are included?

Fraud protection measures included with all LinkPoint payment services are:

• Address Verification System (AVS)
• Card verification schemes (CVV2 and CVC2)
• Merchant-configurable fraud protection. Merchants can block customer names, IP or class C addresses, domain names, and specific credit card numbers. Merchants can also set automatic lockout times. These are set in the Admin section of LinkPoint Central.

For more information on each of these fraud protection capabilities, please refer to the LinkPoint Central Help files or the LPC user manual.

Top

How can I change my fraud protection settings?

Log into https://www.LinkPointcentral.com. Click on Admin, then on Fraud Settings. Please refer to the LinkPoint Central Help files or user manual for further instructions.

Top

Is there a way for me to review transaction activity for my store?

Yes. Log into https://www.LinkPointcentral.com. Click on Reports and choose your preferred report. Please refer to the LinkPoint Central Help files or user manual for further instructions.

Top

What is included in the welcome e-mail?

When your application is approved, you will receive an introductory e-mail titled "Welcome to LinkPoint API". The following information is included in this e-mail:

• your DBA store name
• your store number (represented by a 10-Digit number) which is required to obtain your password
• your User ID number
• your secure Host Name and Port Number
• your digital certificate (embedded in text within the e-mail or at a URL to which you are directed).
• contact information for questions or problems

Top

What if I lose my welcome e-mail?

Welcome e-mails can be resent if the original e-mails are lost. Please contact support@LinkPoint.com to resend your welcome e-mail.

Top

How do I get a pem file?

The owner of the account should have recieved a Welcome e-mail when the mercahnt account was opened. You must have a LinkPoint API account in order to recieve this e-mail. If you lost this e-mail, you will have to call your merchant account provider to have the e-mail resent at 1-800 456-5989 X4100 (human interaction is a security requirement). At the very end of the message (embedded in the e-mail text) will be the digital certificate, which is your pem file. Follow the instructions given in the e-mail exactly to save the digital certificate into a file on your Web server with a .pem extension. Note the location (path) to the pem file.

Top

How do I create my pem file?

At the bottom of the Welcome e-mail is a copy of your digital certificate. If you are using an ISP, a copy of this e-mail should have been e-mailed to your ISP. This certificate should be saved as a file on your Web server with a .pem extension. Copy all characters beginning with the line that states, "-----BEGIN RSA PRIVATE KEY-----" through the end of this e-mail where it states, "-----END CERTIFICATE-----" into a file with a .pem extension onto your Web server. Note the path to the pem file.

Top

What is a digital certificate? How do I get mine? Is that the only certificate I need for my store?

A digital certificate is a key used on the Internet to identify a company or organization and secure transactions between two parties. When you sign up for the LinkPoint API service, you receive a digital certificate. The LinkPoint API software uses this certificate to send SSL-secured payment transactions to the LinkPoint Secure Payment Gateway.

The certificate you receive with the LinkPoint API solution is used ONLY for LinkPoint API purposes--it does not make your Web server secure. You will need to obtain a digital certificate from a certificate authority in order to secure your Web server. Your Web server should be properly secured whenever collecting sensitive information from your customers.

Top

Can you send me the digital certificate?

The digital certificate is sent in the Welcome e-mail to the merchant and the merchant's ISP or CSP. The Welcome e-mail can be resent upon request. For security purposes, we can only send the certificate to those parties authorized on the merchant account. If you are a developer working for a merchant and have not received the digital certificate, you should ask the merchant to forward the "Welcome to LinkPoint API" e-mail to you. Make sure you ask the merchant to send the message as an attachment to ensure that no extra characters are inserted into the digital certificate.

Top

How do I install the digital certificate?

While the installation is fairly simple, it varies depending on the scenario. Basically, you need to copy the digital certificate on the welcome letter as a whole; do not break up the RSA and the Certificate-copy it in one piece.

Follow these instructions carefully:

• Start copying exactly at the first dash of -------Begin RSA and end exactly after the last dash of END CERTIFICATE----- with no extra spaces included.
• Paste it in a text utility and save the file with a .Pem extension. We recommend you use the store number.pem; e.g., 1234123456.pem.
• Review the file name to ensure it has a .pem extension. Make sure you computer view displays all file extensions with no hidden extensions (1234123456.pem.txt will not work). In the Windows^® operating system, under My Computer, select View- Options-View (tab) Hidden files -mark the Show all files and uncheck the box for Hide file Extensions for known file types).
• If you have a hosted site, you will need to find out from your Web hosting company the directory and folder to which you must upload the file via FTP. Some hosts have an area located in the shopping cart where you copy and paste the file instead of using FTP.
• If you host a site on your own Web server, then the file needs to go in the file system where your Web server can access it.

Top

I'm using Java^TM and I've saved my certificate as a PEM file, but it's not working. What do I do?

Java requires the PEM file to be in pkcs12 format. To convert your PEM file to pkcs12 format, run the following from a command prompt:

openssl pkcs12 -export -in YOURPEM.pem -inkey YOURPEM.pem -out YOURPEM.p12 -passout pass:YOURPASS -name "YOURNAME"

Where:

• YOURPEM - the name of your PEM file
• YOURPASS - any password
• YOURNAME - any arbitrary name

For example:

openssl pkcs12 -export -in 1234567.pem -inkey 1234567.pem -out 1234567.p12 -passout pass:987654321 -name "LinkPoint"

The output *.p12 file and the password are used to pass as parameters for JLinkPointTransaction object If you have a problem converting your PEM file, please contact support.

Top

Which shopping carts are integrated with the LinkPoint API solution?

Please see the list of shopping carts on http://www.LinkPoint.com for the latest list of shopping carts. If you do not see the cart you want on the list, please contact us at apisupport@LinkPoint.com. New carts are not added to the list until they have completed the certification process-your cart may already have been integrated, but not yet added to the list.

Top

What if I lose my password?

If you lose or forget your password, please contact us at 1 (877) 229-8739 or at support@LinkPoint.com to reset your password.

Top

How can I test my store before going live?

There is a test server available for merchant testing purposes. Please go to http://www.LinkPoint.com/support/sup_teststore.asp to request a test store. Test accounts are completely separate from your live LinkPoint accounts. If you have any questions about test stores, please e-mail teststore@LinkPoint.com.

Top

Can I set up recurring payments using LinkPoint API software? How about payments in installments?

Yes, you can use the LinkPoint API periodic billing module to set up daily, weekly, monthly, or annual payments and/or payments made at regular intervals in equal installments. You need to pass the fields in the periodic entity to set up a recurring payment.

Top

How do I do API tax calculations?

To use the tax calculator module, you must first create a fulltax line and send it to us for loading to the server. See Using the Tax Calculator for instructions on creating the fulltax line. Please save the file in text format and send it to support@LinkPoint.com.

Top

How do I do API shipping calculations?

To use the shipping calculator module, you must create a shipping and carrier file to be housed on the LinkPoint Secure Payment Gateway. The shipping calculator matches the addressing and shipping carrier information from the shipping context with the appropriate pricing data as defined in your shipping file. Please save the file in text format and send it to support@LinkPoint.com. See Using the Shipping Calculator for further instructions.

Top

What are the absolute 'required' fields for LinkPoint API?

The required fields vary by the type of transaction you wish to perform. Please see the Minimum Required Fields section that applies to the type of transaction you need.

Top

We want to be taken off of test mode and set to live mode? How do we handle this?

If you have been testing with a "live" store, then set the result field in the orderoptions entity to LIVE. If you have been testing with a test store, you need to apply for a live API store and set the result parameter to LIVE. You will also need to change your host name from the staging server host name to the production server host name. You will need to replace your test store number with your live store number. Please refer to the Welcome e-mail for the live store for the production host name and store number.

Top

What does AVS stand for?

The LinkPoint Secure Payment Gateway gives you Address Verification System (AVS) codes to help protect you from costly chargebacks and fraud. Whenever you perform a credit card Sale or Authorize Only transaction, the Gateway verifies the customer's address you entered on the Point of Sale page against the address that the card-issuing bank has on file for the customer. The AVS code tells you how well the two addresses match. If the transaction is approved, you will find the 3-digit alphabetic AVS code in the Approval Code (following the approval number and the reference number) on your Transaction Result page. A typical transaction result code might look like this. The AVS code is highlighted.

0097820000019564:YNAM:12345678901234567890123:

AVS compares the numeric portion of the street address and the zip code. If both the zip code and street address match, the 3-digit AVS code will begin with a Y. If they do not match, the AVS code will begin with an N. An N indicates a higher probability of fraud. The second character of the code will tell you more about the AVS results (see the table below). You will only get an AVS code if the transaction was approved, regardless of whether the addresses match. If you get an AVS code indicating that the address and/or zip code do not match, it is up to you to decide whether you wish to accept the risk and ship the goods to the customer to complete the transaction.

Top

How do I set up AVS?

You don't need to do anything to set up AVS other than to send the following fields in the billing entity. The AVS response will be automatically included in the transaction response code (as described above).

• addrnum
• zip

Top

What is CVV2? CVC2? Discover^® CID?

To help reduce fraud in the card-not-present environment, credit card companies have introduced a card code program. Visa^® calls this code Card Verification Value (CVV); MasterCard^® calls it Card Validation Code (CVC); Discover^® calls it Card ID (CID). The card code is a three- or four- digit security code that is printed on the back of cards. The number typically appears at the end of the signature panel. This helps validate that a genuine card is being used during a transaction, especially in situations like mail orders, telephone orders or Internet orders where the card is not present. All MasterCard cards, both credit and debit, were required to contain CVC2 by January 1, 1997; all Visa cards must contain CVV2 by January 1, 2001. Beginning in October 2003, Discover requires the card code for all Discover transactions. By using the card code results along with the Address Verification Service (AVS), you can make more informed decisions about whether to accept transactions.

A typical transaction result code might look like this. The card code result is highlighted.

0097820000019564:YNAM:12345678901234567890123:

The last alphabetic character in the middle (M) is a code indicating whether the card code matched the card-issuing bank's code. An "M" indicates that the code matched. This code may or may not be present, depending on whether the card code was passed and the service was available for the type of card used. Below is a table showing all the possible return codes and their meanings.

Top

How do I set up CVV? CVC? CID?

You don't need to do anything to set up the card code other than to send the following fields in the creditcard entity. The card code response will be automatically included in the transaction response code (as described above).

• cvmvalue
• cvmindicator

Top

Is there a sample credit card number that I can use to test with my store?

Yes. There are several:

• Visa: 4111111111111 (begin with 4 and 13 digits long total)
• MasterCard: 5111111111111111 (begin with 5 and 16 digits long total)
• MasterCard: 5419840000000003 (begin with 5 and 16 digits long total)
• Amex: 371111111111111 (begin with 37 and 15 digits long total)
• Discover: 6011111111111111 (begin with 60 and 16 digits long total)
• JCB^®: 311111111111111 (begin with 3 and 15 digits long total)

Top

How do I use the LinkPoint API electronic softgood downloads (ESD) module?

You need to send us the file that will be downloaded after purchase. We take that file and post it on the LinkPoint Secure Payment Gateway. Please include all required information necessary, including Store Number. We will send you confirmation when it has been posted. Send files to support@LinkPoint.com. Please allow 72 hours for posting ESD files. See the ESD chapter for further instructions.

Top

Is there a size limit on ESD files?

There is no size limit at this time. However, if you are sending very large files, please contact support@LinkPoint.com to arrange an alternate method of file transfer.

Top

How do I get access to LinkPoint Central?

When you sign up for a LinkPoint Connect or LinkPoint API account, you will automatically get access to the LinkPoint Central service. Log in at https://www.LinkPointCentral.com with your store number, user ID and password.

Top

Our Web server has moved. Do you need to update your records with our new IP address?

Your IP address change does not affect your API account, so we do not need to update our records.

Top

Which credit cards can I accept with the LinkPoint API solution?

Visa, MasterCard, Discover, American Express, JCB, and Diner's Club^®

Top

Is there any way to check authorization of a credit card without having those funds reserved?

No, but depending on the bank, the funds are only reserved for 3-10 days.

Top

What computer platforms are supported?

It depends on the specific language you are using, but, in general, the following platforms are supported.

• Windows NT^® (Versions 4.0)
• BSDI^® (Versions 3.1 & 3.3 & 4.0)
• FREE*Bsd^® (Versions 3.1 & 3.3)
• SUN Solaris^® (Versions 2.6 &2.7)
• HP-UX^® (Versions 10.2 & 11.0)
• Linux^® (Versions 5.2 & 6.x)

Top

How do I run a test transaction?

Run a transaction with the result field in the orderoptions entity set to "GOOD", "DECLINE", or "DUPLICATE".

Top

Troubleshooting

Potential reasons for each error are listed under the error message below.

Top

Unable to open merchant configuration file.

Potential reasons for this error:

• The store number or storename is incorrect. (This is where the store number from the Welcome e-mail should appear.)
• The store number is not present. (Make sure the store number is in the correct place.)
• The host name is wrong. (The host name should be "secure.linkpt.net" or the host name EXACTLY as specified in your Welcome e-mail.)
• The configuration file is missing on the gateway. To test this, we need a copy of your .pem file. Send your questions and .pem file to support@LinkPoint.com.

Top

Unable to open/parse client certificate file.

Potential reasons/fixes for this error:

• Make sure the .PEM file is in the correct location.
• Make sure that everything in the .PEM file (from ----RSA KEY--- to ---End Certificate---) was copied correctly.
• The certificate file could be on an unsupported platform.
• Check the host name (the correct server name is "secure.linkpt.net" or the host name EXACTLY as specified in your Welcome e-mail).
• Check port (the correct port is "1129").
• Check the permissions on the file. Make sure the file is not set to "READ ONLY".

Top

Unable to authorize payment: Unable to connect to SSL server.

Potential reasons/fixes for this error:

• Make sure port 1129 is not blocked in the firewall or router.
• Make sure the secure server is set to the host name specified in your Welcome e-mail and is on port 1129.
• Check to see if our port requires unblocking because the Web server is blocking our port.

Top

N: socket write error (Time out waiting for response)

Potential reasons/fixes for this error:

• Unable to get out of the firewall.
• Make sure that port 1129 is open.
• Your server or our server may be down.

Top

Not an ELF account: (cannot authorize transaction)

Make sure that your operating system is supported. **Unsupported systems include BSDI 4.01 and Digital UNIX.**

Top

Unable to open shipping configuration file

The shipping calculator is an optional module that requires a little extra configuration from your side. Once you have created this file, e-mail it to us at support@LinkPoint.com and we can have it put on the server. Until this file is in place, you will be unable to use the shipping calculator. See Using the Shipping Calculator for further instructions.

Top

Request context must be allocated

You may getting this error because you are passing a 4-digit year (e.g., "2005"). You need to pass a 2-digit month and year (MM & YY) for the card expiration date.

Top

Invalid contact name in merchant certificate

This error is caused when the certificate/pemfile does not match the copy on our side. Please check the following:

1. Be sure you are using the correct certificate/pemfile assigned for your merchant account. If you have more then one merchant account, or a even a test account, please verify you are using the correct certificate. If you do not have a pem file, please see How do I get a pem file?.
2. Make sure you are using the correct configfile/storename. If you use the incorrect storename the certificate/pemfile will not match.
3. Be sure you have created the pemfile correctly. Refer to How do I create my pem file?.
4. Check with your merchant provider that your account is still active.
5. If all the above information is correct, you will want to send a copy of your certificate/pemfile to LinkPoint support (support@LinkPoint.com), who can verify whether the certificate is good.

   Top