TSYS Integration Set Up and Usage Guide (12.11 and earlier)
- Dylan Nigh
In MacPractice 11.6, we've integrated credit card processing services thanks to a partnership with TSYS (formerly known as TransFirst). Now, you can process credit card payments and issue refunds from the ledger. This article covers how the integration works, the set up steps required in MacPractice in order to get started, and the intricacies of using the TSYS integration.
IMPORTANT NOTE: This article covers the TSYS Integration within MacPractice prior to Build 12.15. We've expanded and altered the functionality of some components in Build 12.21+. If you’re on 12.21 and up, please refer to this article instead: TSYS Payment Processing and Recurring Payments - Set Up and Usage Guide (Build 12.21+)
MacPractice Support can assist with the MacPractice integration of TSYS Credit Card Processing, but any issues regarding the hardware or a failure to process a credit card payment should be brought to the TSYS ISV Care Team. TSYS will also provide you with any passwords required for the Card Processing Machines. Their phone number is (855) 882-0507.
Note: TSYS Integration is a paid feature on your MacPractice license. If you are interested in this feature, please contact MacPractice Sales and they'll get you started and connect you with TSYS.
TSYS Preferences and Setup
Before any TSYS functions will work properly, you'll need to connect a PAX Card Processing Machine to the same network as the MacPractice Server via an Ethernet connection, and you'll need the IP address of the Card Processing Machine.
Each MacPractice Client that needs access to a Credit Card Processing Machine will need to perform this step, as the TSYS Preference is a local preference tied to the MP Computer.
Multiple client computers can be tied to a single PAX device. If both clients attempt to process a payment at the same time, the PAX device will queue up the transactions and resolve them in order until this queue is empty.
MacPractice is not able to help your office diagnose any networking issues. Check with your IT or Network Specialist for information on how to properly connect this Card Processing Machine to your office network.
NOTE: You will need the PAX device passcode. This is typically provided by TSYS. If a client has just acquired TSYS, they can find the passcode on the packing slip of the PAX machine. If you do not have the PAX device passcode, please contact the TSYS ISV Care Team.
Once the machine is properly connected to your network, please follow instructions below to check and/or enter the IP Address:
Press F and 1 on the keypad, enter the password provided by TSYS for the Card Processing Machine.
Select Option 2 (Communication) (this is on the second page, they will need to scroll down with the down arrow)
Select Option 1 (LAN Parameters)
Select Option 2 (IP Address)
In order to enter the IP address, you'll need to navigate to the MacPractice Menu > Preferences.
Then, select TSYS in the Sidebar.
In the IP address field, you'll enter in the IP address of the Card Processing Device and click the "Connect Device" button. Once it connects, the TSYS Preferences window will add a few additional options, as shown below.
Reconnect Device: If your card reader loses connection, you can click this Reconnect Device button to attempt to re-connect.
Remove Device: This option will remove the connected device, allowing you to re-enter the IP address for a different device.
Reset Device: This option will interrupt any ongoing interaction and return the credit card reader to an idle state.
Reboot Device: This option will fully reboot the credit card reader, effectively powering it down and restarting it. The device will first finish up all tasks, such as processing credit cards, before rebooting.
Setting the Default Payment Type (optional)
Along with the TSYS integration, we've added a new Ledger Preference: the Default Payment Type (After Entering New Charges). This Ledger Preference is located in the New Charge tab.
This Preference works in conjunction with the "Show Payment Window" option after entering a New Charge. It will automatically select the payment type you have set in the Default Payment Type drop down menu.
It is important to stress that this Preference only needs to be set if you have the "Show Payment Window" preference enabled.
Insurance Credit Card Payment Type
In addition to the new Default Payment Type preference, we've also added in a new Payment Type, Insurance Credit Card, which grants the ability to process Insurance Credit Cards through TSYS. This can be selected like any payment method in the Payments Menu of the Ledger.
It is important to note that the new Insurance Payment Type is available to use regardless of whether you have TSYS enabled on your license.
This change will be reflected in several reports that track insurance payments.
With this addition, you are able to create your own custom payment types for Insurance Credit Cards. You can do this by adding a new type to the Payment Type Reference, located in the References Ability.
The purpose for adding a custom Payment Type is for your organizational purposes. If you want to track a specific type of insurance credit card payment, say from a particular insurance company, you could add a custom Payment Type which you could then track more easily via our Reports.
Setting the TSYS Card Receipt Form (optional)
The last step is to set a Card Receipt Form in Preferences so when you print off a Credit Card Receipt, MacPractice knows which form to use.
You can set this in advance by navigating to Preferences > Forms.
If you attempt to print a credit card receipt and no form is selected, MacPractice will use the Default TSYS Card Receipt Form.
Processing Credit Card Payments with TSYS
When a Credit Card Processing Machine is properly set up in TSYS Preferences and TSYS is enabled on your license, you're ready to begin processing credit card payments.
You'll first navigate to the Ledger, and you'll create a Patient Payment or an Insurance Credit Card payment from the Payment Menu.
The first thing you'll notice when you open up the Payment Window is that the layout is a little different. We took the opportunity when implementing TSYS integration to re-organize the Payment Window for better workflow and clarity.
Without the TSYS feature on your MacPractice license and no valid Credit Card Machine is connected, the Payment Window would look like this. If your Payment Window looks like this, double-check that you have followed the steps in the TSYS Preferences and Set Up section.
When you do have a valid credit card machine connected to this computer, your MacPractice window will instead appear as so:
You'll notice that in the upper right corner, a "Card Entry Method" pop up menu and a new button are available. The pop up menu is used to select the method of processing the credit card payment.
Each of these is a particular method for processing the payment, divided up into three methods; Transmit, Manual, and Forced. We'll describe each one in turn.
Credit - Manual
Credit - Manual allows a user to manually enter in credit card information from MacPractice.
When you enter an amount for the credit card payment and select this option from the Card Entry Method drop down, the button immediately below the drop down menu will change to "Manual Entry".
When you click the Manual Entry button, it'll bring up a window where you can enter the card details. This method has the advantage of not needing the card reader physically present, which is great for situations such as processing payments made through statements or mail. (although the Card Reader must still be available on the same network as the MacPractice Server!)
The Card Number and Expiration Date fields are required. CVV may be necessary depending on how your TSYS account and hardware is configured.
Once you click Submit, you'll be returned to the payment window, and you'll see a spinning wheel below the Manual Entry button. Once it completes, you'll get a confirmation message listed in the Payment Window, as shown in the screenshot below.
From here, the approved credit card transaction will reside in this payment on the ledger. You also have until the credit card batch is closed and approved to void the transaction by using the "Void Transaction" button, which we'll discuss later in Voiding Transactions.
Credit/Debit - Transmit
The Credit - Transmit and Debit - Transmit options both allow you to use a credit/debit card on your card processing device, via swiping, or tapping, or any method the card reader supports. For our purposes, we'll refer to this action as "swiping". The "transmit" phrase refers to transmitting the card information from the machine to MacPractice.
Functionally, the Transmit option works similarly to the Manual option. In the payment window, you'll enter in the Amount as normal, then select the Credit or Debit - Transmit option from the Card Entry Method drop down. Upon selection, you'll see the button below the drop down menu change to "Transmit to Device".
When you click Transmit to Device, the payment window will have a spinning indication that says "Waiting for Device". At this point, you should swipe the credit or debit card.
If you wait too long to swipe a card, the "Waiting for device..." prompt as shown in the above screenshot will time out.
Depending on how your PAX card reader is configured, the patient may need to verify additional information, and will be prompted via the device. When the card processes successfully, you'll see a confirmation message in the Payment Window, much like the Manual method.
Forced Transactions (Credit - Forced)
The last option, Credit - Forced, is used in situations where a card has been initially declined, or there is a problem with processing a card payment.
Normally, the Credit - Forced option when you received a Declined message after attempting to process a card via the first three methods, as shown in the screenshot above.
In this situation, a patient can contact the credit/debit card company's phone number (typically printed on their card) to obtain an Auth (Authorization) code that will allow the payment to be processed.
When you receive the Declined message, select the Credit - Forced Card Entry Method from the drop down. The button will change to "Force Transaction".
When you click this button, a prompt will appear asking for an Auth Code, and the card information again.
The Forced method can also be used to re-enter a credit/debit transaction that was deleted from the card reader, or if the connection from the card reader to TSYS was interrupted. By accessing the transaction/auth # from the TSYS portal and entering it into the Auth Code field, you can re-enter this information into MacPractice without re-processing the card.
Partially Approved Payments
When a credit/debit card is processed and there is not enough available on the card, you may see a Partial Approval prompt window.
This window contains an explanation of the situation, demonstrating that only a portion of the payment was approved. At this point, you can choose, at the patient's discretion, to either Void the transaction and make other arrangements to cover the full payment amount, or you can keep the partial approval and make other arrangements to cover the remainder of the cost.
If you've already applied the payment amount in the Payment Window before processing the card, you may be warned that in the situation of a partial approval, the applied amount will be unapplied in order for the user to apply the partial amount properly.
Receipts
You can print off a credit card receipt for patient credit card payments after running a transaction in the Payment Window by checking the "Print TSYS Card Receipt" checkbox in the Payment Window.
This checkbox is enabled by default on all new payments, and unchecked when opening an existing payment.
Note: This checkbox is not available for Insurance Credit Card payments, you'll need to use the Print TSYS Credit Card Receipt option to print these off manually.
Upon clicking the "Save" button on the Payment Window, a prompt will appear allowing you to select the printer. The printed receipt form matches the dimensions for a DYMO Printer standard size, but you can print it off with any kind of printer.
You can also select the payment or refund in the patient's ledger and select "Print TSYS Card Receipt" from the Print Menu. You can also simply double click the receipt line in the ledger to open up the receipt, allowing you to reprint an existing receipt.
This Print TSYS Card Receipt option will allow you to also print Insurance Credit Card receipts.
Finally, you can print off both patient and insurance credit card receipts from the Transaction Log, which we'll cover in that section.
If you prefer not to have card receipts show in the ledger, you can use the ledger's View Options drop down menu to disable or enable these items.
Voiding Transactions
Voiding a Transaction can be necessary in certain situations, such as the incorrect card being processed.
Transactions are eligible to be voided presuming that the latest credit card Batch has not been closed yet. Batches are covered in the Batch Management section of this article.
There are two methods to void a transaction. First, in the ledger you can open up the payment that holds the credit card transaction and click the "Void Transaction" button, located in the upper right corner of the payment window.
The second method is to navigate to the Transaction Log node of the Accounting Ability, select the payment in question, and select "Void" from the Actions drop down menu. We'll cover this interaction more in the Transaction Log section.
If the batch has already been closed, you'll need to refund the credit card transaction, as the transaction will no longer be able to be voided. In this situation, when attempting to void a transaction, you would see an "Error - Not Found" message.
It is important to stress that deleting a payment DOES NOT void or refund a credit card transaction. If you accidentally delete a payment or refund, you can access your non-ledger card transactions in the Transaction Log in the Accounting Ability.
Refunding to a Credit/Debit Card
On occasion you'll need to issue a refund to a credit or debit card. Thankfully, refunding a credit card payment is as simple as refunding a normal payment.
First, select the payment in the Ledger with the credit card transaction you'd like to refund, and select Refund from the "Other" drop down menu. You will have to unapply the credit card payment from any connected charges prior to refunding.
The Refund window will appear, and you'll see an additional drop down and button for the Card Entry Method much like the Payment Window when processing a new credit card payment.
It is important to note that you can refund a payment to any credit/debit card. It does not need to be the original card that made the transaction.
Much like when processing a payment, you'll select the desired Card Entry Method, with the exception of Credit - Forced, and follow similar steps as described in TSYS Integration Set Up and Usage Guide (12.11 and earlier) | Processing Credit Card Payments with TSYS to process the refund.
If you wish to refund a higher amount than the original payment, you will need to first adjust the original payment's amount in order to refund the higher amount. When adjusting the original payment, you'll likely see an alert warning you that the new amount does not match the card transaction amount as a safety precaution.
Remember that deleting a payment or refund does not void the associated card transactions. If you accidentally delete a payment or refund, you can access your non-ledger card transactions in the Transaction Log in the Accounting Ability.
Refunding to Check
If you find yourself in a situation where you need to issue a refund by check, the best way to accomplish this is to select the credit/debit payment in a ledger, then select Refund as you normally would. You'll still need to ensure that there is an unapplied portion of the payment to refund.
From here, you need to enter something in the Refund Reference # field. We recommend that whatever you use, you type in the method you'll be using to refund.
You do not need to enter in a credit/debit card number in order to process a refund that is issued to a patient via check. With this method, you can ignore the Card Entry Method field and Manual Entry... button.
For example, in the above screenshot we've typed in "Refund to Check" into the Refund Reference # field. When you are satisfied, click OK. This will create a refund line item in the ledger, and you can then proceed with refunding the patient.
Management Tools in the Accounting Ability
This section covers some of the additional tools and information available in the Accounting Ability. These are located in the new "Card Transactions" section of the sidebar. There's a new node for the Transaction Log, and a new node for Batch Management.
If you need to add the Accounting Ability to your toolbar, simply right click any empty space in the toolbar area and click "Customize Toolbar". From this window, you can drag and drop the Accounting Ability to your toolbar wherever you prefer it.
Transaction Log
The Transaction Log contains a history and essential information of all credit card transactions that have been processed through your connected card readers. You're able to search, filter, and perform actions such as voiding/refunding transactions.
You can also create non-ledger transactions from here as well, which are transactions that are not tied to any ledger items.
The layout of the Transaction Log is similar to other nodes in the Accounting Ability. The table will list Transactions in the date range set in the Start Date and End Date. These fields default to today's date.
You can also filter to just see any Non-Ledger Transactions. You can also search for items by using the Search bar. The search bar locates any information in all columns in the current filter configuration. For example, if you search for transactions, and the filter is configured to view today's results, the search will only return any results from today's results.
Double clicking a transaction will take you to that transaction if it's a Ledger Transaction.
The bottom half of the Transaction Log is dedicated to details about the selected Transaction. You'll be able to see the Card Read Method (Manual, Transmit, or Forced), and other details from the card reader.
The Actions Drop down menu will allow you to take certain actions, depending on the transaction selected (if any). The available Actions are:
Void: This action will attempt to Void the selected transaction. Voiding a transaction will only be successful if the current credit card batch is still open. See Batch Management for further details.
It is important to note that a voided transaction will not be displayed when looking at a patient's ledger. If you void a transaction, you should immediately navigate to the patient's ledger to address the payment accordingly. We typically recommend refunding the card payment without entering a credit card so the ledger correctly adjusts the balance accordingly, then adding a comment to that refund to document what happened.Print Receipt: This action allows you to print a credit card receipt for the selected transaction, as described in Receipts. This method does not create a new Receipt ledger item. This option functions for both patient and insurance credit card payments.
Go To Transaction: This action will take you to the selected transaction in the appropriate ledger.
Post as New Patient Payment: This action is used on Non-Ledger Transactions. With a non-ledger transaction selected, you can use this action to post the transaction to a patient's ledger as a new patient payment. You'll be prompted to select the patient you wish to post the payment to. This will allow you to post the payment without having to re-run the credit card transaction.
Post as New Patient Insurance Payment: This action is used on Non-Ledger Transactions. With a non-ledger transaction selected, you can use this action to post the transaction to a patient's ledger as a new insurance payment. You'll be prompted to select the patient you wish to post the payment to. This will allow you to post the payment without having to re-run the credit card transaction.
Post as new Bulk Insurance Payment: This action is used on Non-Ledger Transactions. With a non-ledger transaction selected, you can use this action to post the transaction to a bulk insurance payment for an insurance company. You'll be prompted to select the Insurance Company you wish to post the payment to. This will allow you to post the payment without having to re-run the credit card transaction.
New Non-Ledger Sale: This action is used with no transaction selected. It allows you to run a credit card transaction that is not associated with a ledger patient or insurance payment. You can later post it as a patient/insurance payment with the above "Post as New Payment" actions if you wish. Non Ledger Sales are not reflected on any patient balances and will not appear on reports.
New Non-Ledger Refund: This action is used with no transaction selected. It allows you to run a credit card transaction that is not associated with a ledger refund. This option should be used sparingly, as a blind credit sent to TSYS without a connected transaction will raise a flag with their risk mitigation team and will likely be subject to review by TSYS. Non Ledger Refunds are not reflected on any patient balances and will not appear on reports.
Non-Ledger refunds cannot be tied to any ledger items like Non-Ledger Sales can be.
Batch Management
TSYS will provide more information regarding Batches and how they work and their processes, so this section will focus more on the essentials an office must do within MacPractice to appropriately manage their batches.
In the Batch Management node, you're able to pull information from the previous batch, or you can close the current batch for the currently connected card reader device.
TSYS can be configured to automatically close batches every day so long as there was not a problem with closing the batch. If there has been a problem, the batch will not close, and thus all transactions are not finalized and the transaction amounts are not deposited into your account.
In order to manage this properly, MacPractice recommends taking two steps on a daily basis. Be aware that you will need to perform these actions for each connected card reader device.
On a daily basis, at the beginning of the day's business, click the "Fetch Data From Previous Batch". This will allow you to verify that the previous batch was closed. By clicking this button, you will be given a summary of the previous batch.
If the batch was rejected, you won't see a notice by "Time batch closed" and you may see a rejection message. This is an indication that you'll need to reach out to TSYS for assistance on how to resolve the issue.
Once you have verified that the previous batch has been closed successfully, you're good to go. TSYS can normally auto-close batches on a daily basis, but if you have opted to manually close batches, you'll need to use the "Close Current Batch" button at the end of the day. By closing a batch, you will no longer be able to void any transactions, and this will finalize those transactions, allowing transaction amounts to be deposited into your accounts.
If you see a Rejection message, contact TSYS for assistance.
For any questions regarding batches, or any assistance with resolving a batch that cannot close, please contact the TSYS ISV Care Team at (855) 882-0507.
Shifting Payments To Other AccountsLet's say you accidentally ran a credit card transaction for the wrong account, and wish to post it to the correct account.
In order to accomplish this correction, you'll first need to locate the original payment that has the credit card transaction tied to it. You can either navigate to the patient account if you know it, or you can locate the transaction in the Transaction Log.
Once you've located the payment, you will need to delete it from the incorrect patient's account. You will see a warning that deleting a payment will not void or refund the credit card payment.
By deleting the payment that the transaction is connected to, you will turn this transaction into a Non-Ledger Transaction. These can be located in the Transaction Log.
From there, you can use the Transaction Log Action "Post as New Patient Payment" or the Action "Post as New Patient Insurance Payment". This will create a new payment, either patient or insurance, and the credit card transaction will be tied to this payment.
You will be prompted to select a patient upon selecting this action.
Common Error Messages
We never want to see error messages, but they do provide us information regarding any problems we may be facing. This section can help you interpret what these error messages mean. If you are EVER in doubt, contact MacPractice Support and we can assist you.
Common MacPractice Errors
Unable to parse response from device
Device has sent a response that MacPractice does not expect or is garbled.
Invalid response received from device
Device has sent a response that MacPractice does not expect or is garbled.
Machine Identifier Missing
UUID is somehow missing
These three errors above have to do with the communication being received from the PAX Device. This may indicate a faulty connection or a malfunctioning PAX Device. Troubleshooting steps could include unplugging the PAX Card Reader and re-plugging it in (both power and ethernet connection) and reconnecting the PAX Card Reader via the TSYS Preferences and Setup instructions. If problems persist, please contact TSYS for further information.
Unable to save (card receipt) to database
Unable to save something to the database usually means that there is an connection issue between MacPractice client and MacPractice Server and/or database.
Unable to create ledger item
Unable to create something in the database usually means that there is an connection issue between MacPractice client and MacPractice Server and/or database.
Unable to connect to database to (retrieve connection time, update PAX device connection)
Unable to connect to the database usually means that there is an connection issue between MacPractice client and MacPractice Server and/or database.
Unable to retrieve (connection time, card selection type) from database
Unable to retrieve information from the database usually means that there is an connection issue between MacPractice client and MacPractice Server and/or database.
For the above errors, the common thread between them all is a connection problem between a MacPractice Client computer and the MacPractice Server computer. Troubleshooting steps would include confirming the computer you're using is connected to your network, checking to ensure the Server Computer is running with MacPractice started, and restarting your Server and Client computers.
PAX Card Reader Messages
The following table describes errors and messages that the PAX Card Reader itself will produce in various situations. For more detail on some of these issues, please contact TSYS Support.
Error Code | Error Message | PAX/TSYS Description | Explanation |
|---|---|---|---|
000000 | OK | Approve | The transaction was approved for the amount requested |
000100 | DECLINE | Host Error (See Host Specific Errors) | The transaction was declined for a number of reasons at the financial institution. Contact TSYS with assistance. |
100001 | TIMEOUT | Time out | The device has timed out while awaiting for the card information to process the transaction or timed out while waiting for a response from TSYS/Host. Timeout settings can be adjusted with TSYS on the firmware. This can also be adjusted on the PAX device itself. |
100002 | ABORT | User Aborted | The user or patient pressed cancel on the PAX device (Or a transaction was cancelled or halted in MacPractice) |
100006 | BATCH FAILED | Batch Failed |
|
100011 | DUP TRANSACTION | Duplicate transaction, if the terminal returns this error code the operator should confirm if this is a new transaction. The ECR can resend the pack with “Dup Override Flag” set. | This can indicate that the transaction is identical to a previously made transaction. It could also be an indicator that there is an issue with retaining certain data. We strongly recommend contacting TSYS for more elaboration on what could cause this message, and inform MacPractice Support of the issue. |
100021 | ALREADY VOIDED/ALREADY COMPLETED |
| Already Voided - This indicates that the transaction has already been voided, rendering it null. If this is not anticipated, contact MacPractice Support and we can investigate further.
Already Completed - This indicates that the transaction in question has already been completed. Contact TSYS for more detail. |
100023 | UNKNOW ERROR/NOT FOUND/USER ABORTED/ CANNOT VOID |
| The most common one we will see is NOT FOUND which means the transaction is not found on the device or the batch is already closed. User Aborted could indicate a user cancelled a command or transaction in progress. The best course of action is to contact TSYS for any of these messages. |
| UNSUPPORT EDC | PIN Debit is not enabled on the account | Client will need to reach out to TSYS to enable PIN Debit.
|
| DEVICE RESPONSE - HOST MID NOT SET | The office may be set up with the wrong integration platform on TSYS's end | In this situation, the office may need to contact TSYS at integratedcustomercareoma@globalpay.com in order to be transitioned to the appropriate platform. |