Working with Plug-ins
Plastic 2 is a plug-in for FileMaker Pro and FileMaker Server that processes secure payments within FileMaker.
FileMaker 7 or higher, Java Virtual Machine (JVM) 6 or higher, Windows or Mac OS X 10.6. Rosetta on Intel Macs not supported.
If you unzip the zip archive containing the plug-in files and open the top-level directory, you will find two subdirectories labeled WIN (for Windows) and MAC (for Macintosh). The WIN directory contains two plug-in files, one with a .fmx extension and another with a .fmx64 extension. The file with the .fmx64 extension is only used for FileMaker Server installations, which are explained below. The MAC directory contains a plug-in file with a .fmplugin extension.
To install the plug-in, copy the plug-in from the WIN or MAC folder to one of the directories listed below. Directory paths are listed relative to the parent directory of the installation home directory of the FileMaker application.
FileMaker Pro XX/Extensions
FileMaker Pro XX Advanced/Extensions
FileMaker Server Web Publishing Engine (applies to the entire Web Publishing Engine prior to FileMaker Server 12.0.2 and to Instant Web Publishing only for FileMaker Server 12.0.2 and later)
FileMaker Server/Web Publishing/publishing-engine/wpc/Plugins (create the Plugins folder if it does not exist)
FileMaker Server Custom Web Publishing (applies only to FileMaker Server 12.0.2 and later)
FileMaker Server/Web Publishing/publishing-engine/cwpc/Plugins (create the Plugins folder if it does not exist)
Note: For 64-bit versions of Windows, be sure to use the 360Works plug-in with a .fmx64 extension
FileMaker Server Scripting Engine (applies to FileMaker Server scheduled scripts)
FileMaker Server/Database Server/Extensions
Note: Using the plug-in with the FileMaker Server Web Publishing Engine or the FileMaker Server Scripting Engine requires an Enterprise plug-in license.
Uninstalling the plug-in
Uninstall the plug-in by quitting FileMaker Pro or stopping FileMaker Server and removing the plug-in file from the appropriate Extensions or Plugins directory.
Demo mode and registering the plug-in
Plug-ins will run in a fully featured demo mode until they are registered. While running in demo mode, the plug-in will run for 2 hours at a time. In order to get another two hours of demo time, you must restart FileMaker Pro, FileMaker Server's database server module or FileMaker Server's Web Publishing Engine, depending upon where the plug-in is installed.
To register the plug-in in FileMaker Pro, you may either enter the license information in FileMaker plug-in preferences or by calling
CCRegister inside a script. You must call
CCRegister inside a script in order to register the plug-in for use with FileMaker Server.
Set Variable [ $register; Value: CCRegister ( $licenseKey, $registeredToName) ]
Returns: a 1 on success or a 0 on failure.
When something unexpected happens, the plug-in will pop up a dialog showing what the error message is. This makes it easy to see what went wrong. However, in some cases, you (the developer) may prefer to show your own message to the user, or possibly not show a message at all. In that case, you can call
CCSetErrorCapture ( true ). This will suppress the displaying of error dialogs.
Whether or not you suppress the error dialogs, a plugin function will return the word "ERROR" if something goes wrong. It's a good idea to check the result of each plugin function call to determine if an error occurred. If an error occurs, use the CCLastError function to get a detailed message describing the error. For example:
Set Variable [ $result = MyPluginFunction("x" ; "y" ; "z") ] If [ $result = "ERROR" ] Show Custom Dialog [ "An error occurred: " & CCLastError ] End If
If a plug-in is not installed correctly, all plug-in function calls will return "?"
To check if a transaction succeeded
The simplest way to check to see if money has changed hands in a payment processing function call is to check the result of the function itself. This is extremely useful when calling functions such as
CCProcessPayment and CCProfileProcessPayment. The result of the transaction will give a transaction ID or the word ERROR. Using the
CCLastError like in the example above will give further information about the error, such as if there is no network connectivity, or the card was declined.
Set Variable[$result ; CCProcessPayment(...)] If[$result = "ERROR"] #Transaction is unsuccessful. Below is an example of how you might handle the error. Set Field[Transaction::Error Message ; CCLastError] Else #Transaction is successful. Set Field[Transaction::Transaction ID ; $result] End If
For more information on how to correctly install and work with plug-ins, check out the Plugins 101 documentation.
MJM Innovations provides Taxicard payment processing, and is a supported gateway in Plastic 2. Please check the demo file included as a download with Plastic 2 for an example of its use. These scripts are ready for insertion into your own solution!
Getting an account
You'll need an account using the MJM Innovations gateway, and use your Source ID and the Trip ID as the first two parameters for every plug-in function call that performs a transaction. In the function signature template, you may see the terms merchant account name and transaction key instead of Merchant UUID and API Key. This is due to the fact that Plastic 2 supports many gateways that use different definitions of log-in credentials.
Set Variable [ $result; Value: CCProcessPayment ( sourceId, tripId; ...) ]
Setting the Gateway
Before processing any payments, you need to tell Plastic which gateway you are using. This is done by calling CCSetGateway.
Set Variable [$gateway; Value:CCSetGateway("MJM")]
Returns: 1 if a valid gateway is provided, "ERROR" on failure.
Basic Credit Card Charge
This simple example will run a single charge and requires you to input a card number and expiration date.
Once you properly configure your merchant account, you can quickly and easily process payment transactions.
You must provide the following information for a credit card payment transaction:
- Source ID
- Trip ID
- Dollar amount
- Credit card number
- Driver ID
- Vehicle ID
Returns: the CCProcessPayment function will process a transaction and return a transaction ID. This function returns a transaction ID if the transaction is successful or the word ERROR if the transaction fails. For detailed information about the most recent transaction failure, call the CCLastError function before calling any other transaction-processing function.
In your script, you would then have a second line after setting the gateway.
Set Variable $result Value: CCProcessPayment( sourceId, tripId; dollarAmount; cardNumber; expDate; //Optional "driverId="; "vehicleId="; "gps=")
Note: It is important to store the resulting transaction ID because you may need it later to void the transaction, issue a refund or capture a previously authorized transaction.
You may submit optional parameters to most of Plastic's payment-transaction processing functions. These parameters will be submitted to the payment gateway along with the basic transaction information. Although they are not usually required to process an order, these parameters can be useful for tasks such as address verification or linking a transaction to a customer id or an invoice number. To supply additional parameters to a function call, add them to the end of the parameter list after the last required parameter, using a "key=value" syntax.
Set Variable $result Value: CCProcessPayment( sourceId, tripId; dollarAmount; cardNumber; expDate; //Optional "driverId="; "vehicleId="; "gps="; "passengers=" & Payment::Passenger; "address=" & Payment::Address; "city=" & Payment::City; "state=" & Payment::State; "zip=" & Payment::Zip)
Certain types of merchant accounts are set up for reading physical card swipes, instead of taking orders via the web or over the phone. If you account is a card present account, like a retail store, then you will need to also send the data included on the magnetic stripe of a card. It is important to pass in swipe data if you have it, as your transaction may be downgraded to a more expensive rate if you simply type a card number.
First, set the gateway with card present parameter
To process a card present transaction, first call CCSetGateway with the parameter cardPresent=true. If CCSetGateway returns a 1, then you can perform a card present transaction.
Second, determine your Track 1 and 2 formats
To process a payment using card present accounts, you'll need the information in the magnetic stripe of the credit card. In Plastic, this information may be obtained from a keyboard-emulating card reader, which essentially dumps text into a text field when the card is swiped, as if the text had been entered via a keyboard.
While some card readers will contain software that parses that raw data from the magnetic stripe before dumping it to a field, this documentation refers to those keyboard-emulating readers that dump raw data. Raw swipe data contains two delimited pieces of information: Track 1 and Track 2.
Raw data would look something like this:
Track 1 is delimited by a percent symbol and a question mark, so in the previous example Track 1 would be:
Track 2 is delimited by a semicolon and question mark, so in the previous example Track 2 would be:
See http://www.exeba.com/comm40/creditcardformat.htm for more information about Track 1 and Track 2.
Note: As a convenience, the Plastic function CCTrackData will parse either Track 1 or Track 2 data as a return-separated string containing account code, cardholder name, expiration date (YYMM), and optional discretionary data.
Process the payment with CCProcessPayment
Finally, call CCProcessPayment and pass in raw swipe or track data. When processing a card-present transaction, a gateway will typically require you to pass in either the full raw swipe, Track 1 or Track 2. In most cases, you do not need to pass in card numbers and expiration dates.
MJM Innovations will only accept track 2 data.
Set Variable [$result; Value: CCProcessPayment( sourceId; tripId; dollarAmount; ""; ""; "track2=;1234123412341234=11121010000000000111?")]
Both ways of submitting transactions will accept the following optional parameters:
Plastic includes a number of helper functions that allow users to retrieve data from the gateway or Plastic.
To execute any of these functions inside of a script, use a Set Field or Set Variable script step.
- CCGetCardIssuer(cardNumber) - returns the card issuer for a given card number, either: VISA, MASTERCARD, AMEX, DINERS, DISCOVER, JCB. Returns an error if the card number is from another issuer.
- CCGetLast (name) - returns a value from the most recent transaction response that corresponds with the name parameter.
- CCLastAVS- returns the gateway's Address Verification System Response for the last payment which was processed. This response is typically a one letter indicator, meaning the following:
|A||Street address matches, but 5-digit and 9-digit postal code do not match.||Standard domestic|
|B||Street address matches, but postal code not verified.||Standard international|
|C||Street address and postal code do not match.||Standard international|
|D||Street address and postal code match. Code "M" is equivalent.||Standard international|
|E||AVS data is invalid or AVS is not allowed for this card type.||Standard domestic|
|G||Non-U.S. issuing bank does not support AVS.||Standard international|
|I||Address not verified.||Standard international|
|M||Street address and postal code match. Code "D" is equivalent.||Standard international|
|N||Street address and postal code do not match.||Standard domestic|
|P||Postal code matches, but street address not verified.||Standard international|
|R||System unavailable.||Standard domestic|
|S||Bank does not support AVS.||Standard domestic|
|U||Address information unavailable. Returned if the U.S. bank does not support non-U.S. AVS or if the AVS in a U.S. bank is not functioning properly.||Standard domestic|
|W||Street address does not match, but 9-digit postal code matches.||Standard domestic|
|X||Street address and 9-digit postal code match.||Standard domestic|
|Y||Street address and 5-digit postal code match.||Standard domestic|
|Z||Street address does not match, but 5-digit postal code matches.||Standard domestic|
- CCLastCCV- returns the gateway's Card Code Verification Response for the last payment which was processed. This response is typically a one letter indicator, meaning the following:
- M- CVV2/CVC2 Match - Indicates that the card is authentic. Complete the transaction if the authorization request was approved.
- N- CVV2 / CVC2 No Match – May indicate a problem with the card. Contact the cardholder to verify the CVV2 code before completing the transaction, even if the authorization request was approved.
- P- Not Processed - Indicates that the expiration date was not provided with the request, or that the card does not have a valid CVV2 code. If the expiration date was not included with the request, resubmit the request with the expiration date.
- S- Merchant Has Indicated that CVV2 / CVC2 is not present on card - May indicate a problem with the card. Contact the cardholder to verify the CVV2 code before completing the transaction.
- U- Issuer is not certified and/or has not provided visa encryption keys
- CCLastChargeResult - returns the gateway's result code for the last operation.
- CCLastPaymentAuthCode - returns the gateway's approval code for the last payment which was processed with CCProcessPayment.
- CCLastPaymentTransactionID- returns the gateway's transaction ID for the last payment which was processed with CCProcessPayment.
- CCLastRawResponse- returns the gateway's raw text response for the most recent transaction.
- CCValidateCardNumber (cardNumber) determines if a card number is valid. Does not indicate the validity of the card itself, only its number. Returns either a 1 for valid card, or 0 for invalid cards.
- CCLastError - returns the text of the last error triggered by a plugin function.
- CCLicenseInfo - returns information about the license used.
- CCVersion - returns the version of the credit card plugin which is installed.
If you still need help, there are several resources available! FMForums hosts a support forum for 360Works products. Please look through the posts and see if your question has been posted before making a new topic.
Support is also available via email at firstname.lastname@example.org. You can also call us at 770-234-9293. We offer many services in addition to our plug-ins, so let us know if you'd like a little help integrating the plug-in into your solution. Or if you'd be interested in a customized plug-in or development please let us know!