|
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.
|
|---|
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. |
|---|
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 |
|---|
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. |
|---|
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. |
|---|
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.
Query Output Fields
| Email | | The email address you passed to the function.
|---|
| Valid | "true" or "false" |
|---|
| CleanEmail | The email stripped of non-valid characters. |
|---|
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 Output Fields
| Email | | The email address you passed to the function.
|---|
| Valid | "true" or "false" |
|---|
| CleanEmail | The email stripped of non-valid characters. |
|---|
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 |
|---|
"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 | |
|---|
| CorrelationID | |
|---|
| Version | |
|---|
| Build | |
|---|
| Errors | |
|---|
| Status | "Success" or "Failure". |
|---|
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 | |
|---|
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 | |
|---|
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 | |
|---|
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. |
|---|
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. |
|---|
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.
