Intrafoundation Software

CFX_PayPalAPI - Software

CFX_PayPalAPI (1.8 Beta) November 05 2005 12:00 AM

product id 47

Send related correspondence to: webmaster@intrafoundation.com

Java [w/ Java source code]

Description

What is this? CFX_PayPalAPI is an Java-based Extension Tag for use with Macromedia ColdFusion MX that enables you to directly communicate with (consume) PayPal's new web-service based API.

Due to the way security was implimented with their web service, ColdFusion is, at this time, unable to establish an authorized HTTPS connection with their server. This software overcomes that issue as well as presenting their API in a friendly, query-based manner.

(See the PayPal Developer web site for more detailed information on exactly what services are available from the PayPalAPI. For the sake of clarify, this software attempts to impliment their API verbatum as it is stated in their PDF manuals. (Within the limitations that it is a constantly evolving and changing interface, which, it must be said, apparently has little in the way of review before being published.)

Currently the software supports the following CFML Engines:

If you have any bug reports, suggestions for enhancements or for new features, feel free to email us at webmaster@intrafoundation.com.


Official PayPal Documentation

The official documentation for the Web Service API that this software interfaces with can be found in a set of PDFs on the PayPal web site at the following locations. Please refer to these documents for detailed information on the remote function calls and fields referenced.

Merchant User Manual and Integration Guide (PDF)
API Reference Manual (PDF)

As there is little point in replicating said official data here, the documentation provided with this software shows only the specifics of how it itself interfaces with the web service and any specific differences that may have arisen with its implimentation.

Please see the PayPal PayPal Developers site for detailed information and their official support forum.

Installation

Installation of this software consists of:

  1. Copy the JAR file CFX_PayPalAPI.jar to C:\CFusionMX\cfx\java\ (this varies depending on how and where you installed you CFMX).
  2. Using the CFIDE (ColdFusion Administration) go to the CFX tags section and add this tag.
  3. Using the CFIDE (ColdFusion Administration) go to Java and JVM, then the CLASSPATH field and add
    C:\CFusionMX\lib\cfx.jar, c:\CFusionMX\cfx\java\CFX_PayPalAPI.jar,
    (this varies depending on how and where you installed you CFMX).

This software requires the use of Axis 1.1 which (unless you are using the software in command-line debug mode without ColdFusion MX) will comes with ColdFusion and should automatically already be in the Java CLASSPATH.


Tag Name Class Name Description
CFX_PayPalAPI
com.intrafoundation.CFX_PayPalAPI.CFX_PayPalAPI
CFX_PayPalAPI by Lewis Sellers of Intrafoundation Software - HTTP://www.intrafoundation.com


PKCS12 Certificates: FILE and REGISTRY

All communications with the PayPalAPI requires the transmission of a PKCS12 certificate and its accompanying password. The certificate can either be stored in a FILE or in the Windows REGISTRY.

There are four parameters that control the handling of the certificate: CertStorage, CertFormat, CertLocation and CertPassword.

CertStorage is either "FILE or "REGISTRY".

CertFormat is at this time always "PKCS12".

CertPassword is the password used to authenticate the certificate.

Lastly CertLocation is the actual location that the certificate can be found. If CertStorage is "FILE" this is a file location such as "c:\mycerts\cert1.p12". If CertStorage is "REGISTRY" then this is a registry location in the HKEY_LOCAL_MACHINE hive and the location will look like for example like "SOFTWARE\\Intrafoundation\\cert1".

Updates and the changing PayPal API protocol

PayPal has a somewhat horrible reputation for customer and developer support. Unfortunately. For that reason, and the fact that the API is, unlike some, currently evolving and changing, occasional tweaks to this software may be required. Any such updates to fix minor problems or add completely new Web Service calls are free. Simply inform us of the problem you're having (preferably with some captured details -- scrubbed of sensitive information) and we will of course investigate the issue as son as possible.

Examples

There are several simple CFML scripts included providing examples of how to use this software. You must, of course, install the software first. (See installation).

A few of the examples require you add (in the CFMX administration panel) the included sample Access database "CFX_PayPalAPI.mdb" as "CFX_PayPalAPI".

You must also have a valid PayPal or PayPal Sandbox account and the additional API username/password as well as a valid PayPal PKCS12 certificate/password. All of this may be obtained directly from PayPal itself (by hunting through an admittedly somewhat byzantine website for the said materials.)

Where is this software?

In the folder you installed it to. (Click Start > All Programs > CFX_PayPalAPI then the "Explore CFX_PayPalAPI Folder" icon to go directly there.)

Q: Does it work under platforms other than Windows?

It has not as of yet been tested under any other platforms, however, except for the use of the Windows Registry using a native JNI, it should.

regtool

This software has the ability to read the required PayPal PKCS12 certificates from the Windows Registry. If you are not using software that has already placed your P12 certificate in the registry you can use this simple Java tool to do such for you manually.

Places certificates into the HKEY_LOCAL_MACHINE registry hive.

Uses three arguments: certificate_file_name, registry_subkey_name, key_name.

For example:

C:\> java regtool cert.p12 SOFTWARE\mycompany\certs cert1

You can use regedit or regedt32 to verify the data has been placed into the registry.

APICall Functions

Functions for Tag Status Information

Courtesy functions

PayPal WS API RPC Functions

(Currently) Unsupported or Unofficial PayPal WS API RPC Functions

About

Returns information about the software itself. Of primary interest are the version and builddate.

Query Output Fields Copyright Version BuildDate Licensed LicenseKeyValid LicenseKeyCustomerName
The Copyright © notice.
The version of the software you are using
The date the copy of this software you have was last build
Reports whether the software is operating in licensed mode or not. If in ""licensed"" mode then "true". Otherwise "false".
If license key is valid then "true". Otherwise "false".
The name of the Person/Company/Organization that purchased the LicenseKey being used.
<CFX_PayPalAPI APICall="About" QueryName="PayPalAPIQuery" >

Information

Returns some basic system information that may be of use when interfacing with or using the tag.

NOTE: The number of query fields returned by this function may, with subsequent revisions, expand in size.

Query Output Fields QueryName CurrentDirectory JavaClassPath
The name of the query field this software returns its results in if you do not specify a name.
The folder this software thinks is its "home" folder. This is mainly of interest only if you plan on using your security certificates from the Windows Registry -- A JNI (Java Native Interface) file named "ICE_JNIRegistry.dll" is used to bridge the gap between Java and the Windows Registry, and this file is required to be in the folder this field names.
The current Java CLASSPATH.
<CFX_PayPalAPI APICall="Information" QueryName="PayPalAPIQuery" >

ProtocolVersions

Returns a query list of all the PayPal API protocols the software currently supports or knows about and the protocol level at which it deals with them. (A version of "0.0" indicates the protocol is known but currently not supported.)

For example, the protocols most commonly listed would include:

  1. MassPay
  2. RefundTransaction
  3. TransactionSearch
  4. GetTransactionDetails
  5. AddressVerify
Query Output Fields Protocol Version
Protocol Name
Protocol Version
<CFX_PayPalAPI APICall="ProtocolVersions" QueryName="PayPalAPIQuery" >

CardPreValidation

Performs a series of basic checks against credit card information such as Luhn-mod-10 on card account-number, checks if expiry data is beyond expiration, compares number format to known valid formats.

This function currently can handle popular card formats from: Mastercard ("MASTERCARD"), Visa ("VISA"), Discover ("DISCOVER"), Diner's Club ("DCLUB"), En Route ("ENROU"), and JCB ("JCB").

Input Parameters Issuer Expiry AccountNumber
The issuing organization: I.E. "MASTERCARD","VISA","DISCOVER","DCLUB","ENROU" or "JCB".
The Expiry date: MM/YY.
The acount number: E.X. 4111-1111-1111.
Query Output Fields FormatValid ChecksumValid ExpiryValid IssuerValid CleanAccountNumber Digits
"true" or "false". Reports whether the account number had the proper prefix and digit length as used by the stated issuer.
"true" or "false". Performs a Luhn Mod-10 checksum on the account number to determine if the number is "valid". By this we mean that the built-in typographic digit indicates the account number was mostly likely typed in correctly with no typing mistakes. This does not indicate whether the account number is "valid" in the sense that the card has been actived by a credit card company and is in good standing.
"true" or "false". Compares the stated expiry date to the current date on the server is is running on.
"true" or "false". Checks if the issuer known to this software. NOTE: Even if the card is unknown, the other functions ExpiryValid, ChecksumValid, CleanAccountNumber and Digits will function correctly. Only FormatValid and IssuerValid will depend on known issuers.
Returns the account number stripped of everything except the digits.
Returns a count of the number of "clean" (see CleanAccountNumber) digits.
<CFX_PayPalAPI APICall="CardPreValidation" Issuer="VISA" Expiry="12/06" AccountNumber="4111-1111-1111-1111" QueryName="PayPalAPIQuery" >

MassCardPreValidation

See CardPreValidation for details.

MassCardPreValidation is exactly the same as CardPreValidation except that: Instead of accepting the three parameters Issuer, Expiry, AccountNumber for a single card, it takes as input a standard query with the three fields Issuer, Expiry, AccountNumber.

In this way you can, if you wish, retrieve the three temporary fields directly from an SQL database, and then send them straight to this tag without any further preprocessing.

This software will validate any number of rows of data you send it (within, of course, the limitations of your hardware, operating system and the CFML engine you are utilizing).

Performs a series of basic checks against credit card information such as Luhn-mod-10 on card account-number, checks if expiry data is beyond expiration, compares number format to known valid formats.

This function currently can handle popular card formats from: Mastercard ("MASTERCARD"), Visa ("VISA"), Discover ("DISCOVER"), Diner's Club ("DCLUB"), En Route ("ENROU"), and JCB ("JCB").

Query Input Fields Issuer Expiry AccountNumber
The issuing organization: I.E. "MASTERCARD","VISA","DISCOVER","DCLUB","ENROU" or "JCB".
The Expiry date: MM/YY.
The acount number: E.X. 4111-1111-1111.
Query Output Fields FormatValid ChecksumValid ExpiryValid IssuerValid CleanAccountNumber Digits
"true" or "false". Reports whether the account number had the proper prefix and digit length as used by the stated issuer.
"true" or "false". Performs a Luhn Mod-10 checksum on the account number to determine if the number is "valid". By this we mean that the built-in typographic digit indicates the account number was mostly likely typed in correctly with no typing mistakes. This does not indicate whether the account number is "valid" in the sense that the card has been actived by a credit card company and is in good standing.
"true" or "false". Compares the stated expiry date to the current date on the server is is running on.
"true" or "false". Checks if the issuer known to this software. NOTE: Even if the card is unknown, the other functions ExpiryValid, ChecksumValid, CleanAccountNumber and Digits will function correctly. Only FormatValid and IssuerValid will depend on known issuers.
Returns the account number stripped of everything except the digits.
Returns a count of the number of "clean" (see CleanAccountNumber) digits.
<CFX_PayPalAPI APICall="MassCardPreValidation" Query="mytempcctable" QueryName="PayPalAPIQuery" >

EmailPreValidation

Does a "well-formed" check on an email address you provide to the function. This involves checking it is from a valid top-level domain and in the correct form.

Input Parameters Email
The email address you passed to the function. Query Output Fields Email Valid CleanEmail
"true" or "false"
The email stripped of non-valid characters.
<CFX_PayPalAPI APICall="EmailPreValidation" Email="myname@mycompany.com" QueryName="PayPalAPIQuery" >

MassEmailPreValidation

See EmailPreValidation for details.

MassEmaildPreValidation is exactly the same as EmailPreValidation except that: Instead of accepting Email as an attribute to the functoin call, it takes as input a standard query with the field Email.

In this way you can, if you wish, retrieve a list of emails directly from an SQL database, and then send them straight to this tag without any further preprocessing.

This software will validate any number of rows of data you send it (within, of course, the limitations of your hardware, operating system and the CFML engine you are utilizing).

Does a "well-formed" check on an email address you provide to the function. This involves checking it is from a valid top-level domain and in the correct form.

Query Input Fields Email
The email address you passed to the function. Query Output Fields Email Valid CleanEmail
"true" or "false"
The email stripped of non-valid characters.
<CFX_PayPalAPI APICall="EmailPreValidation" Email="myname@mycompany.com" QueryName="PayPalAPIQuery" > <CFX_PayPalAPI APICall="MassEmailPreValidation" Query=myquerydata QueryName="PayPalAPIQuery" >

The Control Parameters

All functions that call the PayPal Web Service have several common additional parameters that may or must be set. These are, for the most part, used for controlling secure access to the Web Service API and the way the resulting data is returned.

Note that APICall is always required as it determines which function you wish to call.

Control Parameter default values APICall LicenseKey QueryName CertStorage CertFormat CertLocation CertPassword Username Password Subject WSURL Timeout
Determines which function is called.
The license key you are given when purchasing a copy of this software. If not present the only difference is that the software will only connection to PayPal's sandbox site at https://api.sandbox.paypal.com/2.0/ which is used to test the software.
The name given to the query data that a function returns.
Can be FILE or REGISTRY. This tells the software where, in general, you security certificate is to be found.
Currently only PKCS12. The format of the security certificate used by PayPal.
The exact location of the security certificate. For example, if CertStorage is of type FILE: c:\mycerts\cert1.p12 or if CertStorage is of type REGISTRY: SOFTWARE\\mycompany\certs\mycert.
Your PayPal API username. Note: This is different than your PayPal login username and is of a form like: webmaster_api1.intrafoundation.com. It is issued seperately from your PayPal account.
The password for you API username.
https://api.paypal.com/2.0/ if licensed, or https://api.sandbox.paypal.com/2.0/ if not.
Maximum timeout for the call in milliseconds.

Required Control Parameters

  • APICall
  • CertLocation
  • CertPassword
  • Username
  • Password
  • Subject
  • WSURL

Optional Control Parameters

  • LicenseKey
  • QueryName
  • CertStorage
  • CertFormat
  • Timeout
Control Parameter default values APICall LicenseKey QueryName CertStorage CertFormat CertLocation CertPassword Username Password Subject WSURL Timeout
PayPalAPIQuery
FILE
PKCS12
https://api.paypal.com/2.0/ if licensed, or https://api.sandbox.paypal.com/2.0/ if not.
60000
<CFX_PayPalAPI APICall="GetTransactionDetails" QueryName="PayPalAPIQuery" CertStorage="FILE" CertFormat="PKCS12" CertLocation="c:\certs\mycert.p12" CertPassword="mycertpassword" Username="webmaster_api1.mydomain.com" Password="myapipassword" Subject="" WSURL="https://api.sandbox.paypal.com/2.0/" Timeout=60000 QueryName="PayPalAPIQuery" >

"Abstract" Query Return Fields

All PayPal Webservice API functions will always return the following six (6) fields in addition to any other information related to the specific function call.

See official PayPal API documentation for further field information.

Query Output Fields Timestamp Ack CorrelationID Version Build Errors
The time the transaction was performed.
A general acknowledgement token. Usually "success" or "failure".
The protocol version.
The build of the protocol.
A list of errors any warnings, if any, encountered during the API Call. An error/warning consists of four coma separated fields: The error code (such as "10001"), the severity code ("Error", "Warning", etc), the short or more general description of the error and the long or specific description of the error. More than one error/warning may be encountered in a call. Each set of errors is separated by a semicolon (";").

MassPay (PayPal WS API RPC Function)

Pays up to 250 people (PayPal accounts) at a time.

See official PayPal API documentation for further field information.

Parameter Input Fields currencyID
USD, JPY, GBP, EUR, CAD
Query Input Fields ReceiverEmail Amount UniqueID Note
A valid email address the money is to be sent to.
The amount being sent.
A merchant specific ID identifying the receiver.
Note, if any.
Query Output Fields Timestamp Ack CorrelationID Version Build Errors Status
td>
"Success" or "Failure".
<CFX_PayPalAPI APICall="MassPay" Query="mytempcctable" QueryName="PayPalAPIQuery" >

RefundTransaction (PayPal WS API RPC Function)

Refunds the full or a partial amount from a previous transaction. Can currently only be performed once per TransactionID.

See official PayPal API documentation for further field information.

Parameter Input Fields TransactionID RefundType Amount CurrencyCode Memo
The TransactionID or txn_id in question.
"Full" or "Partial"
Amount of currency being refunded. Leave blank if RefundType is "Full".
USD, JPY, GBP, EUR, CAD
Query Output Fields Timestamp Ack CorrelationID Version Build Errors
<CFX_PayPalAPI APICall="RefundTransaction" TransactionID="000000000000001" RefundType="Partial" Amount="5.00" CurrencyCode="USD" Memo="Sorry about the missing USB cable." QueryName="PayPalAPIQuery" >

TransactionSearch (PayPal WS API RPC Function)

Searches through your transactions and returns a list of TransactionIDs based on your search criteria.

Requires the parameter "StartDate". All others are optional.

See official PayPal API documentation for further field information.

Parameter Input Fields (Required) StartDate
Parameter Input Fields (Optional) EndDate PayerEmail ReceiverEmail TransactionClass Amount CurrencyCode Status PayerSalutation PayerFirstName PayerMiddleName PayerLastName PayerSuffix TransactionID ReceiptID AuctionItemNumber
Query Output Fields Timestamp Ack CorrelationID Version Build Errors TransactionID Timestamp Timezone Type Payer PayerDisplayName Status GrossAmount FeeAmount NetAmount
<CFX_PayPalAPI APICall="TransactionSearch" StartDate="1/1/2002" QueryName="PayPalAPIQuery" >

GetTransactionDetails (PayPal WS API RPC Function)

Get detailed information about the transaction identified by TransactionID.

See official PayPal API documentation for further field information.

Parameter Input Fields (Required) TransactionID
Query Output Fields Timestamp Ack CorrelationID Version Build Errors RecieverInfo_Business RecieverInfo_Receiver RecieverInfo_ReceiverID PayerInfo_Payer PayerInfo_PayerID PayerInfo_PayerStatus PayerInfo_Salutation PayerInfo_FirstName PayerInfo_MiddleName PayerInfo_LastName PayerInfo_Suffix PayerInfo_PayerCountry PayerInfo_PayerBusiness PayerInfo_Name PayerInfo_Street1 PayerInfo_Street2 PayerInfo_CityName PayerInfo_StateOrProvince PayerInfo_Country PayerInfo_CountryName PaymentInfo_TransactionID PaymentInfo_ReceiptID PaymentInfo_TransactionType PaymentInfo_PaymentType PaymentInfo_PaymentDate PaymentInfo_GrossAmount PaymentInfo_FeeAmount PaymentInfo_SettleAmount PaymentInfo_TaxAmount PaymentInfo_ExchangeRate PaymentInfo_PaymentStatus PaymentInfo_PendingReason PaymentInfo_ReasonCode PaymentItemInfo_Custom PaymentItemInfo_Memo PaymentItemInfo_SalesTax PaymentItemInfo_Name PaymentItemInfo_Number PaymentItemInfo_Quantity PaymentItemInfo_Options Subscription_SubscriptionID Subscription_SubscriptionDate Subscription_EffectiveDate Subscription_RetryTime Subscription_Username Subscription_Password Subscription_Recurrences Subscription_TermsAmount Subscription_TermsPeriod Subscription_reattempt Subscription_recurring Auction_BuyerID Auction_ClosingDate Auction_multiItem PayerInfo_AddressStatus PayerInfo_AddressName PayerInfo_Phone PayerInfo_PostalCode PayerInfo_ExternalAddressID PayerInfo_AddressID PayerInfo_AddressOwner PayerInfo_InternationalName PayerInfo_InternationalStateAndCity PayerInfo_InternationalStreet
<CFX_PayPalAPI APICall="GetTransactionDetails" TransactionID="0000000000000000001" QueryName="PayPalAPIQuery" >

AddressVerify (PayPal WS API RPC Function)

This function is used to verify that a specified email and address are on file with PayPal and verified.

Note: This function is currently available only to merchants using the PayPal "Enterprise" option. See the following thread on the PayPal forums.

See official PayPal API documentation for further field information.

Parameter Input Fields Email Street ZIP
Customer's email address
First line of street address (that is Street1)
ZIP code
Query Output Fields Timestamp Ack CorrelationID Version Build Errors Email StreetMatch ConfirmCode ZIPMatch CountryCode PayPalToken
The email address you specified.
Response indicating if the street matched. "None", "Matched", "Unmatched".
Response indicating if the email address is on file at paypal.
Response indicating if the ZIP code matched.
The countrycode on file with PayPal that is attached to the email address in question.
A 24-hour token used to prevent address tampering.
<CFX_PayPalAPI APICall="AddressVerify" Email="customer@company.com" Street="Box 1 Main Street" ZIP="12345" QueryName="PayPalAPIQuery" >

BillUser (PayPal WS API RPC Function)

Unofficially under beta testing by PayPal.

BillAgreementUpdate (PayPal WS API RPC Function)

Unofficially under beta testing by PayPal.

TellFortune (PayPal WS API RPC Function)

Semi-official PayPal function for testing connections. Given a "name" it returns with a random fortune-cookie type fortune.

Not implimented.

Parameter Input Fields Name
User name
Query Output Fields Timestamp Ack CorrelationID Version Build Errors Fortune
Your fortune.
<CFX_PayPalAPI APICall="TellFortune" Name="myname" QueryName="PayPalAPIQuery" >

Reference Links

Further technical and practical information may be found at the following locations:

Technologies Involved

This software was developed under Java 1.4 using the Eclipse 3.01 IDE.

Other software, tools or libraries used to create or use in it include:

  • ColdFusion Java CFX API
  • Axis (SOAP) 1.1
  • Xerces 1.4.4
  • com.ice.jni.registry
  • PayPal API
  • Ebay API

Copyright Notice

This software is Copyright (c) 2004 by Lewis A. Sellers of Intrafoundation Software.

Portions of this software make use of:

  1. com.ice.jni.registry by Tim Endres for Windows Registry functions.
  2. Apache Axis 1.1 for SOAP communications and WSDL binding.

Version History

  • v1.5 December 15th 2004.

    Seriously considering dropping the CFX API to see if that will get around one of the two issues that is holding this up....

    It currently works as is on dedicated or single merchant machines however....

  • v1.4 December 9th 2004.

    Limited beta tomorrow.

    Currently there only two issues to be resolved, though they are serious issues: 1) Getting the SSLFactory to work without affecting the global Axis properties and 2) passing the cert to the SSLFactory with other than static variables.

    It's very quiet among the dev communities as how to manage either of these which has me a little worried it might not be possible at all.

  • v1.3 December 4th 2004.

    First full beta version. Removed ProxyHost/ProxyPort options as it is most likely best (for shared server situations) to simply let the webmaster use the JVM parameters http.proxyhost and http.proxyport

  • v1.2 beta. November 23rd 2004
  • v1.1 beta.
  • v1.0 beta.

Software Development Stages

There are four stages in software development: ALPHA, BETA, GAMMA and OMEGA.

Alpha is where programming for the software is still heavily ongoing. If you can start up the program without it rebooting the computer you're generally happy.

Beta is where you've gotten a great bulk of the program working (sort of) and you're letting other people try it out to test if they can use it or crash it.

Gamma is also sometimes called being "Gone Gold". It's publically (or commercially) released software. If it's in a box or shrink-wrap it's Gamma (you hope).

Omega is the absolute final release. Not all software publishers do this, but it is when they decide they're never going to work on the software again and generally release the entire thing for free, sometimes with the full source code.

[Manual friendly version]

> > >     [ PDF Manual ]    

Download

There is nothing to download.


Gallery

Related External Links

Comments



August 25 2012 04:17 PM

Scheduled to be repackaged and uploaded soon.

1008,1008


 
CACHE: Selectively not caching this page.