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:
- Copy the JAR file CFX_PayPalAPI.jar to C:\CFusionMX\cfx\java\
(this varies depending on how and where you installed you CFMX).
- Using the CFIDE (ColdFusion Administration) go to the
CFX tags section and add this tag.
- 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
| CFX_PayPalAPI |
Class Name
| com.intrafoundation.CFX_PayPalAPI.CFX_PayPalAPI |
Description
| 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
| The Copyright © notice. |
Version
| The version of the software you are using |
BuildDate
| The date the copy of this software you have was last build |
Licensed
| Reports whether the software is operating in licensed mode
or not. If in ""licensed"" mode then "true". Otherwise "false". |
LicenseKeyValid
| If license key is valid then "true". Otherwise "false". |
LicenseKeyCustomerName
| 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
| The name of the query field this software returns its
results in if you do not specify a name. |
CurrentDirectory
| 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.
|
JavaClassPath
| 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:
- MassPay
- RefundTransaction
- TransactionSearch
- GetTransactionDetails
- AddressVerify
Query Output Fields
Protocol
| Protocol Name |
Version
| 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
| The issuing organization: I.E.
"MASTERCARD","VISA","DISCOVER","DCLUB","ENROU" or "JCB". |
Expiry
| The Expiry date: MM/YY. |
AccountNumber
| The acount number: E.X. 4111-1111-1111. |
Query Output Fields
FormatValid
| "true" or "false". Reports whether the account number had
the proper prefix and digit length as used by the stated issuer. |
ChecksumValid
| "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. |
ExpiryValid
| "true" or "false". Compares the stated expiry date to the
current date on the server is is running on.
|
IssuerValid
| "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. |
CleanAccountNumber
| Returns the account number stripped of everything except
the digits. |
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
| The issuing organization: I.E.
"MASTERCARD","VISA","DISCOVER","DCLUB","ENROU" or "JCB". |
Expiry
| The Expiry date: MM/YY. |
AccountNumber
| The acount number: E.X. 4111-1111-1111. |
Query Output Fields
FormatValid
| "true" or "false". Reports whether the account number had
the proper prefix and digit length as used by the stated issuer. |
ChecksumValid
| "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. |
ExpiryValid
| "true" or "false". Compares the stated expiry date to the
current date on the server is is running on.
|
IssuerValid
| "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. |
CleanAccountNumber
| Returns the account number stripped of everything except
the digits. |
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.
The email address you passed to the function.
Query Output Fields
Email
Valid
| "true" or "false" |
CleanEmail
| 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.
The email address you passed to the function.
Query Output Fields
Email
Valid
| "true" or "false" |
CleanEmail
| 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
| Determines which function is called. |
LicenseKey
| 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. |
QueryName
| The name given to the query data that a function returns.
|
CertStorage
| Can be FILE or REGISTRY. This tells the software where, in
general, you security certificate is to be found. |
CertFormat
| Currently only PKCS12. The format of the security
certificate used by PayPal. |
CertLocation
| 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.
|
CertPassword
Username
| 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.
|
Password
| The password for you API username. |
Subject
WSURL
| https://api.paypal.com/2.0/ if licensed, or
https://api.sandbox.paypal.com/2.0/ if not. |
Timeout
| 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
| PayPalAPIQuery |
CertStorage
| FILE |
CertFormat
| PKCS12 |
CertLocation
CertPassword
Username
Password
Subject
WSURL
| https://api.paypal.com/2.0/ if licensed, or
https://api.sandbox.paypal.com/2.0/ if not. |
Timeout
| 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
| The time the transaction was performed. |
Ack
| A general acknowledgement token. Usually "success" or
"failure". |
CorrelationID
Version
| The protocol version. |
Build
| The build of the protocol. |
Errors
| 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
| A valid email address the money is to be sent to. |
Amount
| The amount being sent. |
UniqueID
| A merchant specific ID identifying the receiver. |
Note
| Note, if any. |
Query Output Fields
Timestamp
Ack
| td>
|
CorrelationID
Version
Build
Errors
Status
| "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
| The TransactionID or txn_id in question. |
RefundType
| "Full" or "Partial" |
Amount
| Amount of currency being refunded. Leave blank if
RefundType is "Full". |
CurrencyCode
| USD, JPY, GBP, EUR, CAD |
Memo
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
| Customer's email address |
Street
| First line of street address (that is Street1) |
ZIP
| ZIP code |
Query Output Fields
Timestamp
Ack
CorrelationID
Version
Build
Errors
Email
| The email address you specified. |
StreetMatch
| Response indicating if the street matched. "None",
"Matched", "Unmatched". |
ConfirmCode
| Response indicating if the email address is on file at
paypal. |
ZIPMatch
| Response indicating if the ZIP code matched. |
CountryCode
| The countrycode on file with PayPal that is attached to
the email address in question. |
PayPalToken
| 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"
>
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:
-
com.ice.jni.registry
by Tim Endres for Windows Registry functions.
- 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.
![[Valid RSS]](/images/icons/valid-rss.png "Validate my RSS feed"){kind=icon}
August 25 2012 04:17 PM
Scheduled to be repackaged and uploaded soon.