360Works Plastic/Documentation
360Works Plastic User Guide
The CreditCardProcessor provides easy credit card processing capabilities for FileMaker Pro.
Using the plugin
Consult the "CreditCardProcessor Example.fp7" Filemaker file which contains examples of plugin usage. For additional help troubleshooting the Plastic plugin, consult the <a href="http://wo.360works.com/cgi-bin/support/productsupport.cgi/Product_Support">360Works Product Support Wiki</a>.
You must have an active merchant account with a company such as <a href="http://authorize.net">Authorize.net</a> or <a href="http://www.paypal.com/cgi-bin/webscr?cmd=_merchant-outside">PayPal Payflow Pro</a> to use this plugin. Note: Authorize.net test accounts will not work, you must have a full account. Once you have an account, obtain a transaction key in the Account/Security Settings/Transaction Key area on the <a href="https://account.authorize.net/">account.authorize.net</a> website.
Selecting a gateway provider
Before you begin processing charges, you need to tell the plugin what type of gateway account you are using. This is done by calling CCSetGateway and passing in your gateway type. If you skip this step, it is assumed you are using an Authorize.net account.
CCSetGateway("Authorize.net") // for Authorize.net accounts (the default)
CCSetGateway("PayPal") // for Payflow Pro accounts
Running Charges
Once your merchant account is set up correctly, running charges can be done in one quick step. Here is an example of its usage:
CCProcessPayment( merchantAccount; transactionKey; chargeAmount; cardNumber; expDate )
The above method will process a payment transaction for a card, and return the gateway transactionID for the transaction, or the word "ERROR",
if the transaction fails for some reason. For additional information about the failure, call CCLastError.
It is important that you store this resulting transactionID, you may need it to VOID the transaction later.
The minimum amount of information needed to process a transaction is:
- Authorize.net merchant account name
- Authorize.net transaction key (obtained at <a href="https://account.authorize.net/">https://account.authorize.net/</a>)
- credit card number
- credit card expiration date
- dollar amount
There are numerous additional optional parameters you can provide such as addresses, email, po number, etc. These are not usually required to process an order, but can be useful for address verification purposes or linking a transaction with a customer or invoice. To supply additional parameters, add them as extra parameters onto the end of your function call in the form 'key=value', like this:
CCProcessPayment( merchantAccount; transactionKey; chargeAmount; cardNumber; expDate; "chargeDescription=" & description; "cardType=" & cardType; "verificationCode=" & securityCode )
Here is a list of the most common valid additional parameters:
- authMode</dt>
- used to process authorization-only transactions. See CCProcessPayment for more information.
- firstName</dt>
- first (given) name of the credit card holder</dd>
- lastName</dt>
- last (surname) of the credit card holder</dd>
- companyName</dt>
- company name on the credit card</dd>
- chargeDescription</dt>
- brief description of the charges</dd>
- verificationCode</dt>
- the numeric verification code on the credit card. This is also known as the Card Security Code (CSC), sometimes called Card Verification Value (CVV), Card Verification Value Code (CVVC), Card Verification Code (CVC), or Verification Code (V-Code or V Code) </dd>
- cardType</dt>
- the type of credit card being processed (visa, mastercard, etc)</dd>
- invoiceNumber</dt>
- an arbitrary invoice number for your records</dd>
- poNumber</dt>
- an arbitrary purchase order number for your records</dd>
- customerId</dt>
- an arbitrary customer id for your records</dd>
- address</dt>
- the billing address street address</dd>
- unitNumber</dt>
- the billing unit/apt no.</dd>
- city</dt>
- the billing address city</dd>
- state</dt>
- the billing address state</dd>
- zip</dt>
- the billing address zip</dd>
- country</dt>
- the billing address country</dd>
- phone</dt>
- the cardholder's phone numer</dd>
- fax</dt>
- the cardholder's fax numer</dd>
- shipFirstName</dt>
- the shipping recipient's first name</dd>
- shipLastName</dt>
- the shipping recipient's last name></dd>
- shipAddress</dt>
- the shipping street address</dd>
- shipCity</dt>
- the shipping address city</dd>
- shipState</dt>
- the shipping address state</dd>
- shipZip</dt>
- the shipping address zip</dd>
- shipCountry</dt>
- the shipping address country</dd>
- shipCompanyName</dt>
- the shipping recipient's company name</dd>
- email</dt>
- the cardholder's email address</dd>
- currency</dt>
- currency of the transaction amount (
USD, for example)</dd> - track1</dt>
- track1 data from a card reader<a href="#track">*</a>.</dd>
- track2</dt>
- track2 data from a card reader<a href="#track">*</a>.</dd>
- url</dt>
- an alternate url to which to send a gateway transaction (particularly useful for Authorize.Net emulators)</dd>
- user</dt>
- if you set up one or more additional users on the account, this value is the ID of the user authorized to process transactions (Payflow Pro only)</dd>
- partner</dt>
- The ID provided to you by the authorized PayPal Reseller who registered you for the Payflow Pro service. Usually this value is either PayPal or VeriSign.</dd>
- tender</dt>
- Set The tender type (method of payment) <a href="#tender">**</a>.</dd>
- proxyAddress</dt>
- The host address of a proxy server. Required to run Payflow Pro transactions via proxy.</dd>
- proxyPort</dt>
- The port number of a proxy server. Required to run Payflow Pro transactions via proxy.</dd>
- proxyLogon</dt>
- The username for an account used to access a proxy server. Pay</dd>
- proxyPassword</dt>
- The password for an account used to access a proxy server.</dd>
Void/Refund Parameters: These parameters are only used in the CCVoidPayment and CCRefund functions:
- cardNumber</dt>
- The credit card number being voided (this is optional for CCVoidPayment)</dd>
- expirationDate</dt>
- The expiration date of the credit card number being voided, in MM/YY format (this is optional)</dd>
Card-present transactions
Before attempting to perform a card-present transaction, make sure your gateway merchant account is configured for processing card-present transactions. Before performing a card-present transaction using the CCProcessPayment function, you must first call the CCSetGateway function, passing in the optional parameter "cardPresent=true". If the CCSetGateway function returns a 1, then you can perform a card-present transaction using the syntax below.</p>
Authorize.net
A card-present transaction should pass in Track 1 or Track 2 data using the additional parameters track1 and track2.
Track 1 and Track 2 are parts of the raw string generated when a credit card is passed through a magnetic stripe card
reader. See <a href="http://www.exeba.com/comm40/creditcardformat.htm">http://www.exeba.com/comm40/creditcardformat.htm</a>
for a description of the Track 1 and Track 2 data formats.
Note: You do not have to pass in a card number and or an expiration date when performing a card-present transaction; the Authorize.Net gateway will read this information directly from the track data. Make sure you pass in empty quotes ("") for those parameters. </p>
CCProcessPayment( merchantAccount; transactionKey; chargeAmount; ""; ""; "track1=B4111111111111111^CardUser/John^111110100000019301000000877000000" )
Payflow Pro
A card-present transaction using Payflow Pro should also pass in Track 1 or Track 2 data using additional parameters.
However, you must pass in empty strings for the card number and expiration date.
</p>
CCProcessPayment( merchantAccount; transactionKey; chargeAmount; ""; //notice the empty string in place of the cardNumber ""; //notice the empty string in place of the expirationDate "track2=;4912000033330026=15121011000012345678?" )
Tender param options (Payflow Pro only)
A = Automated clearinghouse
C = Credit card
D = Pinless debit
E = Electronic check
K = Telecheck
P = PayPal
Voiding previous transactions
To void a transaction, you need the transactionID which was returned by the CCProcessPayment function. Pass this (along with other payment info) to the CCVoidPayment function. See the function documentation for an example of voiding a previous transaction.
Crediting / Refunding previous transactions
To credit a transaction, you need the transactionID which was returned by the CCProcessPayment function. Pass this (along with other payment info) to the CCRefund function. This is similar to the void process, but accepts a dollar amount.
CCRefund(
settings::merchantAccount ;
settings::transactionKey ; // your transaction key or password
"1321353789" ; // the transactionID being credited
"1234" ; // the last four digits of the credit card number
0.02 ; // the amount of the refund
"expirationDate=" & Date(12, 1, 2010) ; // credit card expiration date
"firstName=John" ; // card holder first name
"lastName=Doe" ; // card holder last name
)
360Works Plugin Setup Guides
See Plugins_101 for Error reporting, installation, registration, and more.
Function Summary
- CCGetCardIssuer ( cardNumber ) — Returns the card issuer for a given card number.
- CCLastAVS — Returns the gateway's Address Verification System Response for the last payment which was processed with {@link #CCProcessPayment}.
- CCLastChargeResult — Returns the gateway's result code for the last operation.
- CCLastError — Returns the text of the last CC-related error which occurred.
- CCLastPaymentAuthCode — Returns the gateway's approval code for the last payment which was processed with {@link #CCProcessPayment}.
- CCLastPaymentTransactionID — Returns the gateway's transaction ID for the last payment which was processed with {@link #CCProcessPayment}.
- CCLastRawResponse — This function returns the gateway's raw text response for the most recent transaction.
- CCLicenseInfo — Returns information about the license used
- CCParam ( key ; value ) —
- CCProcessAuthorizedPayment ( merchantAccountName ; txKey ; previousTransactionID{; dollarAmount ; key1=value1; key2=value2; ...} ) — This function is used to process an authorize-only transaction.
- CCProcessPayment ( merchantAccountName ; txKey ; dollarAmount ; cardNumber ; expirationDate {; key1=value1; key2=value2; ...} ) — This is the primary function used to process credit card charges.
- CCRefund ( merchantAccountName ; txKey ; previousTransactionID ; cardNumber ; amountToCredit {; key1=value1; key2=value2; ...} ) — This transaction credits all or part of an original transaction to the customer.
- CCRegister ( licenseKey ; registeredTo ) — Registers Plastic.
- CCSetErrorCapture ( errorCapture ) —
- CCSetGateway ( gatewayName { ; cardPresent=true } ) — Switch which gateway to use (the default is authorize.net).
- CCSetTestMode ( testModeSetting ) — Puts the credit card plugin into test mode.
- CCTrackData ( trackData ) — Parses track1 or track2 data, returning extracted data as return-separated values.
- CCValidateCardNumber ( cardNumber ) — Utility function for validating whether a credit card number is valid.
- CCVersion — Returns the version of the credit card plugin which is installed.
- CCVoidPayment ( merchantAccountName ; txKey ; previousTransactionID{; key1=value1; key2=value2; ...} ) — Voids a previously processed payment.
Function Detail
CCGetCardIssuer ( cardNumber )
Returns the card issuer for a given card number. Only works for the following card issuers.
- Visa
- MasterCard
- American Express
- Discover
- Diner's Club
- JCB
cardNumber
CCLastAVS
Returns the gateway's Address Verification System Response for the last payment which was processed with CCProcessPayment. To use this, you must first process a payment. If you call this without processing a payment first, it will return the following error:
You must process a payment with the CCProcessPayment function before calling this function
The code will be one of the following:
A = Address (Street) matches, ZIP does not
B = Address information not provided for AVS check
E =
AVS error
G = Non-U.S. Card Issuing Bank
N = No Match on Address (Street) or ZIP
P = AVS
not applicable for this transaction
R = Retry – System unavailable or timed out
S = Service not
supported by issuer
U = Address information is unavailable
W = 9 digit ZIP matches, Address
(Street) does not
X = Address (Street) and 9 digit ZIP match
Y = Address (Street) and 5 digit ZIP
match
Z = 5 digit ZIP matches, Address (Street) does not
Note: This feature is currently only implemented for the Authorize.net gateway.
CCLastChargeResult
Returns the gateway's result code for the last operation. This is a numeric response where the code equals a status type. For authorize.net, the codes are:
- Approved
- Declined
- Error
For Payflow Pro, a '0' indicates success; a negative value indicates a failure.
CCLastError
Returns the text of the last CC-related error which occurred. This should be called any time that a plugin function returns "ERROR" to get a user-readable description of the error.
"" if there was no error.
CCLastPaymentAuthCode
Returns the gateway's approval code for the last payment which was processed with CCProcessPayment. You must process a payment before calling this function.
CCLastPaymentTransactionID
Returns the gateway's transaction ID for the last payment which was processed with CCProcessPayment. This number identifies the transaction in the system and can be used to submit a modification of this transaction at a later time, such as voiding or crediting the transaction.
Generally, the CCProcessPayment function returns this value as well. This function is here as a convenience if you're not able to retrieve that value due to chaining multiple functions together.
You must process a payment before calling this function.
CCLastRawResponse
This function returns the gateway's raw text response for the most recent transaction.
CCLicenseInfo
Returns information about the license used
CCParam ( key ; value )
CCProcessAuthorizedPayment ( merchantAccountName ; txKey ; previousTransactionID{; dollarAmount ; key1=value1; key2=value2; ...} )
This function is used to process an authorize-only transaction. See the documentation for the CCProcessPayment function for instructions on how to submit an authorize-only transaction.
The second parameter (txKey) should be your 16-digit Authorize.net transaction key.
You can obtain an Authorize.net transactionKey by logging into https://account.authorize.net/ and going
to the Account / Settings / Transaction key section.
Payflow Pro only supports passwords, not transaction keys. If you have a Payflow Pro merchant account, simply use your Payflow Pro account password for the second parameter to this function.
In most cases, the fourth parameter (dollarAmount) may be any amount less than or equal to the amount
of the transaction identified by the third parameter (previousTransactionID).
To pass in additional parameters, see the documentation and examples at the top of this document.
If successful, this function returns the unique transactionID for the payment (as assigned by the payment gateway).
If you wish to void the payment later with the CCVoidPayment function, you will need this number!
Note: if test mode is enabled, a successful Authorize.net transaction will return 123456789.
merchantAccountName- your payment gateway merchant account name
txKey- your payflow Pro merchant account password or Authorize.net transaction key
previousTransactionID- the id of the previously authorized transaction to be processed
dollarAmount- the amount of the transaction
detailed information about the nature of the error).
CCProcessPayment ( merchantAccountName ; txKey ; dollarAmount ; cardNumber ; expirationDate {; key1=value1; key2=value2; ...} )
This is the primary function used to process credit card charges. The initial five parameters are required values for every transaction.
The second parameter (txKey) should be your 16-digit Authorize.net transaction key.
You can obtain an Authorize.net transactionKey by logging into https://account.authorize.net/ and going
to the Account / Settings / Transaction key section.
Payflow Pro only supports passwords, not transaction keys. If you have a Payflow Pro merchant account, simply use your Payflow Pro account password for the second parameter to this function.
To perform an authorize-only transaction without submitting it for settlement, you must pass in an additional parameter named authMode.
and set its value to AUTH_ONLY using the following format: 'authMode=AUTH_ONLY'.
To pass in additional parameters, see the documentation and examples at the top of this document.
If successful, this function returns the unique transactionID for the transaction (as assigned by the payment gateway).
If you wish to void the transaction with the CCVoidPayment function or submit an authorize-only transaction for settlement with the
CCProcessAuthorizedPayment function, you will need this number!
Note: if test mode is enabled, a successful Authorize.net transaction will return 123456789.
merchantAccountName- your payment gateway merchant account name
txKey- your payflow Pro merchant account password or Authorize.net transaction key
dollarAmount- the amount of the transaction
cardNumber- the credit card account number to charge for the transaction
expirationDate- the expiration date of the credit card being charged. Format the expiration date as MMYY or MM/YY or MM/DD/YY
detailed information about the nature of the error).
CCRefund ( merchantAccountName ; txKey ; previousTransactionID ; cardNumber ; amountToCredit {; key1=value1; key2=value2; ...} )
This transaction credits all or part of an original transaction to the customer.
Refund transactions must reference a transaction ID, which identifies the transaction that serves as the source of the refund. Transactions must have been settled before they can be refunded; however, you may void unsettled transactions (see CCVoidPayment). The amount to be refunded must not exceed the total amount of the original transaction, less the total amount of any previous refunds to the same transaction.
To pass in additional parameters, see the documentation and examples at the top of this document.
merchantAccountName- your payment gateway merchant account name
txKey- your Payflow Pro merchant account password or Authorize.net transaction key
previousTransactionID- the transactionId of a previously processed transaction.
cardNumber- the credit card account number to credit for the transaction. For Authorize.net credits, you may either pass the entire card number, or just the last four digits. This value is not required by the Payflow Pro gateway, therefore you may pass an empty string ("").
amountToCredit- the amount to credit, as a positive number. Must be less than or equal to the original transaction amount. If a negative number is passed, the absolute value is used. If using the Payflow Pro gateway, you may enter an empty string ("") for this parameter if you wish to perform a full refund.
CCRegister ( licenseKey ; registeredTo )
Registers Plastic.
licenseKey- a valid license key string
registeredTo- the name for the license key used
CCSetErrorCapture ( errorCapture )
CCSetGateway ( gatewayName { ; cardPresent=true } )
Switch which gateway to use (the default is authorize.net).
The following gateways are supported:
- PayPal
- Authorize.net
This plugin function takes additional arguments. Currently the only optional argument is whether submitted transactions are to be processed as SWIPE (card-present) transactions.
If you are using the plugin for card-present transactions, pass cardPresent=true as an optional parameter.
For example:
CCSetGateway("Authorize.net" ; "cardPresent=true");
If you do not specify a value the default is false (card-not-present mode).
gatewayName- one of the supported gateway names.
CCSetTestMode ( testModeSetting )
Puts the credit card plugin into test mode. Pass in a 1 for test mode or 0 for real mode. When in test mode, all credit card charges will be sent to a special test server that runs the normal verification process, but does not run real charges.
testModeSetting- 1 or 0
CCTrackData ( trackData )
Parses track1 or track2 data, returning extracted data as return-separated values. This is convenient if you're swiping card data and want to save the cardholder name to your database, for example. Note: When passing track1 data to the CCProcessPayment function, use the raw swipe data from the card, not this parsed version!
Use the GetValue function in FileMaker to get the following specific values:
- Account Code
- Cardholder Name with leading & trailing whitespace removed (this will be empty for track2 data)
- Expiration Date (YYMM format)
- Optional Discretionary Data
Sample Usage
Set Variable[$data = mytable::swipe] Set Variable[$accountNumber = getValue($data ; 1)] Set Variable[$cardHolderName = getValue($data ; 2)] Set Variable[$expirationYYMM = getValue($data ; 3)] Set Variable[$additionalData = getValue($data ; 4)]
This is primarily for use in card-present transactions. See http://www.exeba.com/comm40/creditcardformat.htm for a description of the track1 and track2 data formats.
trackData- track1 or track2 data from card reader
CCValidateCardNumber ( cardNumber )
Utility function for validating whether a credit card number is valid. This only checks the format of the card number, not whether it is an active account.
This can be very handy for "validated by calculation" fields, to ensure that only valid credit cards are entered.
cardNumber- credit card number, containing numbers and optional dashes
CCVersion
Returns the version of the credit card plugin which is installed.
CCVoidPayment ( merchantAccountName ; txKey ; previousTransactionID{; key1=value1; key2=value2; ...} )
Voids a previously processed payment. The parameters are similar to the CCProcessPayment function, except
dollarAmount is replaced with the addition of the previousTransactionID parameter. The
previousTransactionID should be the transactionID 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.
To pass in additional parameters, see the documentation and examples at the top of this document.
Here is an example of voiding a previous transaction whose transaction ID is 123:
CCVoidPayment (
Settings::merchantAccount ;
Settings::transactionKey ;
123 ; // the previous transaction key
"cardNumber=4444444444444441" ;
"expirationDate=04/08" ;
"firstName=Bob" ;
"lastName=Smith"
)
merchantAccountName- your payment gateway merchant account name
txKey- your Payflow Pro merchant account password or Authorize.net transaction key
previousTransactionID- the transactionId of a previously processed transaction. Note that CVoidPayment 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 CCProcessPayment instead.
information about the nature of the error).
