API Documentation Classic and REST Versions

Getting Started

linked2pay (or L2P) offers a series of ways to seamlessly integrate your existing system with our award winning payments processing platform. Through our Checkout feature and WebService API Kits we have made it even easier for you to find what you've been looking for.

Before you start using/testing our web service features, make sure you register for a Sandbox account!

If you would like to try our JSON-oriented web Service features without downloading our sample applications, click here to check it out!

Authentication For the safety of your account

We care about your account security, that is why we need to make sure all users will authenticate their accounts before making a successful web service call.

Currently, we provide two ways for users to authenticating themselves.

KEY: a Web Service Access Key is generated for you as an alternative "password". You can generate a new Web Service Access Key whenever you want and do not have to go through the process of changing your password every now and then.

FINGERPRINT: this is a more advanced way of authentication: we generate a temporary FINGERPRINT string for you and you can use it for a limited time.

How does the authentication work?  Take a look

How is FINGERPRINT generated?  Take a look

Below are the methods and datatypes used for authentication.

Complex Type: L2PAuthenticationData

Description

Object passed as the first parameter of every method. linked2pay web service calls can be authenticated in two different ways, via KEY Authentication or FINGERPRINT Authentication. Here are the details on how to authenticate your web service calls.

Content Model

Contains elements as defined in the following table:

Component Type Occurs Description
SEQUENCE 1..1
AuthenticationMethod string 1..1

There are two types of Authentication Method,"KEY" and "FINGERPRINT" Authentication.

"KEY" Authentication: Represents when User authenticates their web service call by providing linked2pay with their Login Username and their Web Service Access Key.

"FINGERPRINT" Authentication: Represents when User authenticates their web service call by providing linked2pay with their Login Username, Sequence Number, Time Stamp, and Fingerprint.

login string 1..1 L2P client login name up to 20 characters
key string 1..1

A unique string for authentification purpose, generated and saved on user's Web Service Settings section in the "My Settings" page.

To generate this Web Service Access Key follow these instructions:

  1. Login to linked2pay using your Username and Password
  2. Click on the "My Settings" link located at the upper right-hand corner of the page
  3. Scroll down and expand the "Web Service Settings" section
  4. Mark the "Enable Web Service" check box
  5. Click on the "Generate Web Service Access Key" button
  6. Click on the "Save Changes" button
fingerprint fingerprintBlock 0..1 A bundle of information, containing user's sequence number, timestamp and a 16-character generated fingerprint
Complex Type: fingerprintBlock

Description

fingerprintBlock consists of Sequence Number, Time Stamp, and Fingerprint.

Content Model

Contains elements as defined in the following table:

Component Type Occurs Description
SEQUENCE 1..1
sequence long 1..1

A sequence of numbers that is set by the user which can be any random set of numbers or some set of numbers that make sense to the User.

This sequence number will be used in the mathematical calculation used to generate Users fingerprint.

timestamp long 1..1

Time Stamp is the number of seconds from 01/01/1970 to the current time.

This time stamp will be used as a variable in the mathematical calculation used to generate Users fingerprint.

fingerprint fingerprintType 1..1

A unique and temporary string of 16 characters generated from parameters including current timestamp, sequence number, login ID, and web service access key for the User.

Login Username: The Username of your login credentials used to login to the linked2pay web site.

Web Service Access Key: The Web Service Access Key generated on the My Settings page of the linked2pay web site.

The program to generate fingerprints is available in forms of Java, C#, and PHP.

PHP code:

									
<?php
// This sample code requires the mhash library for PHP versions older than
// 5.1.2
// The following lines generate fingerprint.
// PHP versions 5.1.2 and newer have the necessary hmac function built in.
// For older versions, it will try to use the mhash library.
if ( phpversion() <= '5.1.2' )
{ $fingerprint = hash_hmac("md5", $loginID . "^" . $sequence . "^" . $timeStamp, $transactionKey); }
else
{ $fingerprint = bin2hex(mhash(MHASH_MD5, $loginID . "^" . $sequence . "^" . $timeStamp, $transactionKey)); }
?>
								

Java Code:

package com.jcx.web.services.l2p.data;

import java.security.InvalidKeyException;
import java.security.NoSuchAlgorithmException;
import java.security.SecureRandom;

import javax.crypto.Mac;
import javax.crypto.SecretKey;
import javax.crypto.spec.SecretKeySpec;

public class FingerprintGenerator {
  private long sequence;
  private long timeStamp;
  private String fingerprintHash;
  /**
  * Get the sequence that was used in creating the fingerprint.
  * @return the sequence
  */
  public long getSequence() { return Math.abs(sequence); }
  /**
  * Get the timestamp that was used in creating the fingerprint.
  * @return the timeStamp
  */
  public long getTimeStamp() { return timeStamp; }
  /**
  * Get the fingerprint hash.
  * @return the fingerprintHash
  */
  public String getFingerprintHash() { return fingerprintHash; }
  /**
  * Creates a fingerprint with raw data fields.
  *
  * @param loginID
  * @param transactionKey
  * @param sequence : this number will be concatenated with a random value
  * @return A Fingerprint object.
  */
  public static FingerprintGenerator createFingerprint(String loginID, 
                                  String transactionKey, long sequence)
  {
    FingerprintGenerator fingerprint = new FingerprintGenerator();
    // a sequence number is randomly generated
    SecureRandom generator = new SecureRandom();

    // Sequence is generated. 
    fingerprint.sequence = Long.parseLong(sequence + "" 
	                                      + generator.nextInt(1000));

    // A timestamp is generated.
    fingerprint.timeStamp = System.currentTimeMillis() / 1000;

    // This section uses Java Cryptography functions to generate a fingerprint.
    try
    {
      // First, the Transaction key is converted to a "SecretKey" object.
      SecretKey key = new SecretKeySpec(transactionKey.getBytes(), "HmacMD5");

      //A MAC object is created to generate the hash
      //using the HmacMD5 algorithm.
      Mac mac = Mac.getInstance("HmacMD5");
      mac.init(key);

      String inputstring = null;

      inputstring = loginID + "^" + fingerprint.sequence + "^"
	  + fingerprint.timeStamp;
    
      byte[] result = mac.doFinal(inputstring.getBytes());

      // Convert the result from byte[] to hexadecimal format.
      StringBuilder strbuf = new StringBuilder(result.length * 2);
      for (byte aResult : result)
	  {
          if (((int) aResult & 0xff) < 0x10) {
               strbuf.append("0");
          }
          strbuf.append(Long.toString((int) aResult & 0xff, 16));
      }

          fingerprint.fingerprintHash = strbuf.toString();
    }
    catch (NoSuchAlgorithmException nsae) {
        System.out.println("Fingerprint creation failed. " + nsae.getMessage()); }
    catch (InvalidKeyException ike) {
        System.out.println("Fingerprint creation failed. " + ike.getMessage());}
    return fingerprint;
    }
}
								

C# Code:

namespace L2PPaymentApplication
{
  class FingerprintGenerator
  {
    public string GenerateFingerPrint(int SequenceNumber, string UTCDate, 
	                            string TransactionKey, string APILoginId)
    {
      string StringValue = APILoginId + "^" + SequenceNumber.ToString() + "^"
                                         	  + UTCDate.ToString();

      //The encoding type must be ASCII if reading from the web.config
      byte[] _Key = Encoding.ASCII.GetBytes(Convert.ToString(TransactionKey));

      byte[] _StringToHash = Encoding.ASCII.GetBytes(StringValue);
	  System.Security.Cryptography.HMACMD5 _HMAC_MD5 = 
	                        new System.Security.Cryptography.HMACMD5(_Key);

      byte[] _HashedString = _HMAC_MD5.ComputeHash(_StringToHash); 

      //Convert the byte array back into a string...
      string _return = System.BitConverter.ToString(_HashedString);
      //The bitconverter returns the string with "-" 
	  //between the byte elements.example: C9-85-92-44....
      return _return.Replace("-", "");
    }
    //Method Name:GetUTC()
    //Description:This is a simple function to get the UTC in seconds
    public int GetUTC()
    {
      TimeSpan _TimeSpan = (System.DateTime.Now.ToUniversalTime()
                         	  - System.DateTime.Parse("1/1/1970"));
      return Convert.ToInt32(_TimeSpan.TotalSeconds);
    }
    //Method Name:GetSuquenceNumber()
    //Description:This method generate random sequence number
    public int GetSuquenceNumber()
    {
      Random RndSequenceNumber = new Random();
      return RndSequenceNumber.Next(1, 1000000);
    }
  }
}
								
Simple Type: fingerprintType

Derived By

Restricting string.

Restrictions

  • Length of value must be equal to 16.

Direct Payment Features

The Direct Payment WebService is ideal for expediting both ACH and Credit Card payments for which you already have payment information and the required authorization on file.

Just call our Direct Payment WebService with the payment and authorization information. linked2pay will process the transaction, and you will receive a transaction reference number that can be used for your reporting needs.

Read More

Online Forms Features

Call our Online Forms WebService to add a single invoice manually or an infinite number of invoices through an upload process. Other than the addition of invoices you have the ability to use our Online Forms WebService to update or remove any invoice attachment

Read More

Email Payments Features

Send Credit Requests

Use the Email Payments WebService to easily send a payment to someone via email. The recipient accepts the credit to their account on our secure payment page, you and your payee receive a payment receipt via email and the loop is closed.

Send Debit Requests

Quickly submit a debit request by calling our Email Payments WebService. linked2pay will deliver a debit request to the email you specified with a link to our secure payment page directing payment to your company.

Read More

Reporting Features

The Report WebService allows you to drill down on your requests based on a series of search parameters that can be used individually or in unison. These search parameters include, but are not limited to, 'Request ID', 'Amount', 'Transaction Number', 'Contact Email', etc.

Read More