Celero

Revision as of 17:50, 20 October 2023

Working with Plug-ins

Plastic 4 is a plug-in for FileMaker Pro and FileMaker Server that processes secure payments within FileMaker.

Requirements

FileMaker 7 or higher, Java Virtual Machine (JVM) 6 or higher, Windows or Mac OS X 10.6. Rosetta on Intel Macs not supported.

Installation

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

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.

Error Handling/Reporting

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

More Information

For more information on how to correctly install and work with plug-ins, check out the Plugins 101 documentation.

Celero

Celero can process a wide variety of transactions, and supports terminals, payment tokens and profile-based payments. For detailed examples of each of these transactions.

Getting an account

If you do not already have a gateway or merchant account, you can sign up for a Celero account at the following:

https://www.celerocommerce.com/card-processing

You'll provide your API Key as the first parameter for every plug-in function call that performs a transaction. Celero doesn't require a second parameter to interact with the API, however the function signatures do require it, so an empty string must be provided to allow the functions to execute. In the function signature template, you may see the terms merchant account name and transaction key; this is due to the fact that Plastic 4 supports many gateways that use different definitions of log-in credentials.

Set Variable [ $result; Value:
CCProcessPayment (
merchantAPILoginID;
merchantTransactionKey; ...) ]

Getting credentials in the gateway.

Step 1:

Step 2:

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("Celero"; "cardPresent=true")]

Returns: 1 if a valid gateway is provided, ERROR otherwise.

Working With Terminals

Listing Connected Terminals

You will need the terminal ID to process a transaction. That's often included on the Terminal itself, but Plastic 4 also allows you to get a list of active terminals so that you can programmatically manage payment traffic. You only need to provide your API key as the merchantAccount parameter. You can provide an empty string for transaction key.

Set Variable [$result Value: 
CCListTerminals(
merchantAccount; 
transactionKey;
)]

This method will return a JSON array of objects. The shape of the return JSON structure is below.

[
  {
   "description":"SANDBOX 360 WORKS",
   "serial_number":"1181948765558",
   "id":"c8tqau46lrsdf3d939g",
   "status":"active"
  }
]

Using the Terminals

Terminals use is available only with the CCProcessPayment function. When processing a transaction, you are required to provide the additional parameters of "methodOfPayment" and "terminalID". For "methodOfPayment" you provide "TERMINAL" and for "terminalID" you'll provide the ID of the terminal you want to send the transaction to.

Set Variable [$result Value: 
CCProcessPayment(
merchantAccount; 
transactionKey;
chargeAmount;
cardNumber;
expDate)]

Processing Payments

Basic Credit Card Charge

This simple example will run a single charge and requires you to input a card number and expiration date. To prevent this information from being saved in your database and to simplify PCI compliance, jump to the #Payment Profiles section.

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:

• merchant account name (API key)
• transaction key (Must provide an empty string)
• dollar amount
• credit card number
• credit card expiration date (Format the expiration date as MMYY or MM/YY or MM/DD/YY)

In addition to standard manual entry, Celero allows credit cards to be processed through tokenization and terminals. In those cases, credit card number and credit card expiration date will need to be sent as empty strings. To switch to these payment methods, use the optional parameters specified in the section below.

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(
merchantAccount; 
transactionKey;
chargeAmount;
cardNumber;
expDate;
"methodOfPayment=" & TERMINAL;
"terminalID=" & Payment::yourTerminalID;)]

Returns: a transaction ID from the payment gateway service if the order is successful, or "ERROR" if there was a problem

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(
merchantAccount; 
transactionKey;
chargeAmount;
cardNumber;
expDate;
"methodOfPayment=" & Payment::methodOfPayment;
"paymentToken=" & Payment::paymentToken]

Additional Parameter Listing

Authorizing and Capturing Payments

A sale transaction for credit card contains two parts: an authorization which verifies and places a hold for the amount, and a capture, which actually transfers the funds.

To run an authorization, pass in an additional parameter authMode=AUTH_ONLY.

Set Variable [$result Value:
CCProcessPayment(
merchantAPILoginID,
merchantTransactionKey;
chargeAmount;
cardNumber;
expDate;
authMode=AUTH_ONLY)]

Returns: a verification code from the payment gateway service if the order is successful, or "ERROR" if there was a problem

After running an authorization, run the appropriate CCProcessAuthorizedPayment. Pass in the previousTransactionId from the transaction ID you received from the process with authMode.

Set Variable [$result Value: 
CCProcessAuthorizedPayment(
merchantAPILoginID;
merchantTransactionKey;
previousTransactionId;
dollarAmount)]

The dollarAmount is not required to process the authorized payment.

Voiding Transactions

Set Variable [$result; Value:

CCVoidPayment (
merchantAccount ;
transactionKey ;
previousTransactionID)]

Void a transaction that is pending settlement. Where applicable, a void will be processed as an auth reversal. The parameters are similar to the CCProcessPayment function, except dollarAmount is replaced with the addition of the previousTransactionID parameter. The previousTransactionID should be the transaction ID of the transaction you wish to void. This value is returned by the CCProcessPayment function. Alternately, you can use the CCLastPaymentTransactionID function to get the transactionID of the last processed payment.

Parameters:

merchantAccount - your payment gateway merchant account name (API Key).
transactionKey - your merchant account password OR transaction key (Empty String).
previousTransactionID - the transactionId of a previously processed transaction.

Note that CCVoidPayment will only work on orders that have not settled yet, which means that it will generally only work on payments made that same day. To void settled orders, use CCRefund instead.

Returns: the transactionID from the payment gateway service if the order is successful, or "ERROR" if there was a problem

See also: CCLastPaymentTransactionID: the transactionID from the payment gateway service if the order is successful, or "ERROR" if there was a problem (use CCLastError for more detailed information about the nature of the error).

Crediting or Refunding Transactions

To credit a transaction, you need the transaction ID returned by CCProcessPayment. Pass this (along with other payment info) to the CCRefund function. This is similar to the void process, except it accepts a dollar amount and the credit card number (or the last four digits of the credit card number) used to process the original transaction.

Set Variable [$result; Value:
CCRefund(
  merchantAPILoginID;
  merchantTransactionKey;
  transactionID;
  cardNumber;
  dollarAmount)]

Returns: the transactionID from the payment gateway service if the order is successful, or "ERROR" if there was a problem

Payment Profiles

Customer Profiles

Plastic 4 features customer profiles, which allow you to submit customer and payment information to be reused for future transactions. This greatly simplifies PCI compliance, and keeps sensitive information out of your database. To get started, first you'll need to create a customer in the system. This will return an ID that you can then store. After that, attach a payment method to this newly created customer. This will return a payment ID, which together with the customer profile ID, you can run charges against.

To create a customer in the system, set the following:

Set Variable[$customerID; Value:
CCProfileCreateCustomer (
merchantAccountName;
txKey;
customerId)

Returns: the customer profile ID used to reference the newly created profile if successful, or "ERROR" if there was a problem

Note: If you provide an empty string to customerId, the gateway will generate and return one.

After creating a customer, it can also be updated, deleted, or retrieved. Retrieving a customer will return the information the gateway has saved about the customer.

Returns: 1 if successful, or "ERROR" if there was a problem

On Celero, the functionality of CCProfileGetShipping and CCProfileGetPayment are wrapped into CCProfileGetCustomer, which returns a JSON of the profile (referred to a "Customer Vault: in Celero). CCProfileGetCustomer returns this JSON. An example of the returned JSON can be found here: https://sandbox.gotnpgateway.com/docs/api/#get-customer-record-by-id

To parse out these values, use FileMaker's built in JSON functions.

Additional Parameter Listing

Creating Payment Profiles

Payment profiles allow you to save payment information straight to the gateway for future use. Celero allows you to create payment profiles using a credit card or a payment token. When creating a payment profile with a payment token, you must pass the paymentToken optional parameter with a unexpired payment token. When the paymentToken optional parameter is passed, the required credit card info fields are ignored. To create a payment profile, call CCProfileCreatePayment. Credit cards are created with CCProfileCreatePayment and updated with CCProfileUpdatePayment.

Returns: CCProfileCreatePayment or CCProfileCreatePaymentACH returns the payment profile ID used to reference the newly created profile if successful, or "ERROR" if there was a problem.

Returns: CCProfileUpdatePayment returns a 1 on success, or ERROR if there was a problem.

After creation, payments can be retrieved with CCProfileGetPayment. Certain gateways can validate a payment with CCProfileValidatePayment. Payments can be deleted with CCProfileDeletePayment.

Returns: CCProfileValidatePayment and CCProfileDeletePayment return a 1 on success, or ERROR if there was a problem.

Creating Shipping Profiles

After creating customers and payments, address record information can also be attached to a customer. Address records are only distinguished at billing or shipping when provided as additional parameters billingID or shippingID at the time of a transaction.

Returns: CCCreateShipping returns the shipping ID on success, "ERROR" on failure. CCProfileGetShipping returns the shipping ID on success. Other functions return 1 on success, or "ERROR" if there was a problem.

Running Charges Against Profiles

You can process a payment, authorize a payment, capture an authorized payment, void, and refund transactions. Please note that for unlinked credits with CCProfileRefund, do not pass in an accountNumber or routingNumber.

If you want to run authorize only transactions, use CCProfileProcessPayment and add "authMode=AUTH_ONLY" to the list of parameters. To then capture that transaction, run CCProfileProcessAuthorizedPayment.

Getting Response Information and Using Helper Functions

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:

• 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.

Getting Help

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 plugins@360works.com. 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!