The InstaMed Application Program Interface (API) is a way to access InstaMed Connect so users can interact with the InstaMed Platform to send and receive healthcare and payment transactions.
InstaMed Connect uses industry leading transport encryption to protect data in transit.
- InstaMed Connect Batch Interface uses the AES-256 bit encryption as the standard channel encryption.
- InstaMed Connect Real-Time Interface leverages TLS with certificates provided by a leading certificate authority (CA).
Use any of the following technologies to integrate with InstaMed’s solutions:
REST is a lightweight and easy-to-learn technology used in all areas of web development for integration of web services.
HTTP POST Name Value Pair (NVP) is a simple to use format that works across all platforms.
- Authentication: Basic authentication using your InstaMed Account ID (e.g., [email protected]) and password
- Exceptions: Returned in the format of errorCode=400&errorMessage=An unexpected error occurred with Reference Number 02198MGNBZ
- Content-Type/Format: application/x-www-form-urlencoded
- Request Example: amount=1&transactionType=CreditCard&..
- Response Example: responseCode=000&transactionStatus=C
SOAP Web Services utilizing SOAP version 1.1 or SOAP version 1.2 to transport data. Connectivity requires 2048 bit TLS security.
- Data Exchange: For EDI, the input EDI is passed as a single string parameter, and the response is returned as a string response value; otherwise, a remote object is defined for request and response fields
- Authentication: Basic authentication using your InstaMed Account ID (e.g., [email protected]) and password
- Text Encoding: Default is UTF-8, other encodings may be supported
- Exceptions: An error message is returned as a SOAP exception
How to Generate Web Service Proxy
Download the WSDL (recommended)
- Navigate to one of the following URLs
- Healthcare Transactions – https://connect.instamed.com/healthcare/service.asmx
- Payment Transactions – https://connect.instamed.com/payment/service.asmx
- SSO Polling – https://online.instamed.com/providers/Forms/WebServices/SSOService.asmx
- Enter your credentials when prompted
- Click Service Description when the Web Service page loads
- In Internet Explorer, go to Page > Save As and save the WSDL as Service.wsdl
- In your development enviroment, add a web reference and point it to the Service.wsdl located on your file system (i.e., C:\Service.wsdl)
- Remove :8005 from the WSDL file where present
Support for EMV card functionality and non-keyboard emulation devices is available through the InstaMed .NET API.
- Keyboard emulation devices work seamlessly in a thin client environment, do not require a driver to be installed and do not require a third-party library to be integrated into an application.
- Non-keyboard emulation devices including HID, Serial, and Ethernet require a third-party library and/or driver to be installed. Because of the complexity in supporting non-keyboard emulation devices, software vendors have tried to avoid integrating with them. It is important to note that check scanning also requires non-keyboard emulation devices.
The InstaMed Connect .NET API is a library built using .NET 4.5 and makes it easy for software vendors to:
- Support Payments 2.0 (EMV and NFC) transactions
- Integrate with InstaMed Connect using the HTTP FORM POST/NVP (name-value pair) format
- Integrate with non-keyboard emulation devices
- Support non-keyboard emulation devices in thin client environments (i.e., Citrix)
- Integrate with eCheck scanners
Available Payment Transactions
The following Payment Transactions are available via the InstaMed Connect .NET API:
- Card – EMV/NFC/Swipe/Manual Entry
- Simple Refund
- Save on File
- Single Sign-On payment transactions (via Content Redirection)
- Patient present and patient not present remote deposit check transactions
The vendor will initiate an instance of a class that implements the IDeviceManager interface contained in InstaMed.Connect.API.Interfaces.dll and perform InitializeAsync and ProcessTransactionAsync on it.
.NET Initialization Flow
.NET API Payment Flow
Applications can receive real-time notifications whenever a transaction is processed or updated via the InstaMed Webhook interface.
With webhooks enabled, InstaMed sends a simple HTTP POST containing the relevant transaction information (i.e. Patient info, Amount, Transaction Date, TransactionID, etc) to the application URL in the requested format (JSON, XML, NVP).
Response and Error Handling
Return a HTTP status code 200 only if you successfully store the webhook message. If the HTTP post is not successfully stored, return “Status-Code” indicating the post was not successful (ex. “400” or “500”). Along with a standard HTTP “Status Code” optionally include a “Response Phrase” which InstaMed can parse and pass as the Webhook Posting Message for client review and reference.
If the initial webhook post is unsuccessful, InstaMed retries the webhook post every 30 minutes for up to five attempts. InstaMed assigns the transaction a pending posting retry workflow status when a message is being re-attempted. If after five attempts the terminal message is unsuccessful, InstaMed assigns a posting error workflow status. If InstaMed does not receive or has an issue receiving a Status for a Webhook HTTP post, the post will timeout for 20 seconds, and then retry. After two attempts the post will fail.
In order to secure a webhook end point, it is recommended that the following InstaMed IP addresses be whitelisted:
Authentication is an optional security method. There are three main options:
- Certificate-based (public key) authentication: InstaMed can use Certificate Based Mutual Authentication (Mutual SSL Authentication) to initiate the webhook with the customer’s server. Certificate authentication can be added to either Basic Authentication or Open Authentication protocols.
- Basic authentication (username/password): InstaMed can use the verified authentication version (leveraging a username and password challenge) of Basic Authentication to deliver a webhook.
- Open Authorization (OAuth 2.0): InstaMed can use the recognized ID service Ping Federated 2.0 to exchange a secure token with the customer in order to deliver the webhook. Contact an InstaMed Implementation Manager for information on using other ID services.
InstaMed can use either Basic or Open Authentication, but not both for a specific webhook. A certificate can be used for either Basic or Open if desired.
PLEASE NOTE: Authentication is not available for Member Payments when using the InstaMed Webhook interface
Notifications Available via Webhook
Webhook supports all messages including asynchronous messages and messages generated from the InstaMed platform, including:
Payment Plan Triggers
Note: The TransactionID received via the real-time notification can be used to process a void or simple refund via the InstaMed API.
Webhook Samples Wizard
Polling Payment Response
As an alternative to webhook, which is based on sending notifications from InstaMed to an application, applications can receive real-time notifications by polling InstaMed about a specific transaction. This allows for real-time notification without requiring unsolicited messaging from an outside system that may be blocked by firewalls and security features. Using a token generated through an SSO session, an application can determine whether a transaction has been processed or updated.
Initiating a polling response is done by getting the status of the token and then getting the transaction details once the token is complete.
Get Token Status
- URL: https://online.instamed.com/Forms/WebServices/SSOService.asmx
- Method: GetSSOTokenStatus
- After performing SSO and loading a page to the RelayStateURL, poll https://online.instamed.com/Forms/WebServices/SSOService.asmx every 10 seconds for up to 15 minutes (token expiration time limit)
- While the token status = NEW, sleep for 10 seconds
- If the taken status = EXPIRED, the SSO session expired before the transaction was completed
- If the token status = complete, retrieve the payment details (see the following example)
Get Transaction Details
- URL: https://online.instamed.com/payment/NVP.aspx
Request merchantID=6011000551245&storeID=001&terminalID=002&transactionAction=ViewReceipt&requestToken=false&singleSignOnToken=NTJmY2Y5NmMtOTg2Yi00NDM0LTk2ZWYtZjc3OGE1OTVhN2Qz& Response IsEMVVerifiedByPIN=false&isEMVTransaction=false&EMVCardEntryMode=Swiped&cardBrand=VISA&cardExpirationMonth=6&cardExpirationYear=2017&cardBINNumber=411111&cardHolderName= &lastFourDigits=1111&authorizationNumber=A3807B&responseCode=010&responseMessage=Partially Approved $1.00&transactionStatus=D&primaryTransactionID=0ca7530a86084b468fff132ab7f04491&authorizationText=I AGREE TO PAY THE ABOVE AMOUNT ACCORDING TO MY CARD HOLDER AGREEMENT.&transactionID=0ca7530a86084b468fff132ab7f04491&transactionDate=2016-01-15T20:37:21.5238539Z
Use the InstaMed Connect Posting API over Secure File Transfer Protocol (SFTP).
- InstaMed Connect supports versions 3 through 5 of SFTP (versions 1 and 2 are not currently used) on the SSH 2 protocol.
- InstaMed Connect also supports FTPS (i.e., FTP over TLS), which is a commonly used extension of the FTP protocol with added support for Transport Layer Security (TLS) encryption.
Systems access the InstaMed Connect site to upload and/or download files. Additionally, distinct directories are available for each account or group within an account to ensure confidentiality of data.
- Production Environment Host Name: connect.instamed.com
- Staging Environment Host Name: connect-staging.instamed.com
The InstaMed Connect Posting Interface supports the following authentication mechanisms for each account:
- Username (not including a domain) and password
- Public Key Authentication, using an RSA Public key of 1024, 2048 or 4096 bit length
InstaMed Connect Secure FTP (SFTP) leverages the following ports:
- Port: 22 for username + password authentication
- Port: 2201 for public key authentication
InstaMed Connect uses explicit, passive FTP over TLS (FTPS), leveraging the following ports:
- Session Control Port: 21
- Inbound Data Port Range: 28000-30000
The InstaMed Connect Socket Interface currently supports integrated eligibility and patient import transactions with several major accounting systems. Transport over TCP/IP sockets requires a VPN or leased line connection. TLS may be supported; please inquire.
- Data Exchange: The XML or EDI is passed directly on the socket.
- Authentication: Requires VPN, port setup and connection using an IP and port number.
- Text Encoding: Default is UTF-8. Other encodings may be supported; please inquire.
- End Transmission Character: The character ‘0’ of the configured text encoding is used to specify the end of the transmission. Other options are available.
- Exceptions: A TA1 will be returned if it was not possible to process the inbound request.
Eligibility processing is asynchronous, and ANSI X12 EDI formats are supported. The interface uses queues to manage inbound requests and outbound responses. The socket interface supports two models for managing eligibility socket connections. The first is a persistent model where the connection is prevented from closing. In the non-persistent model, connections are opened only when transactions are ready to be transmitted.
In the persistent model, the InstaMed Connect Socket Interface manages both inbound and outbound connections with the use of “keep alive” messages that are acknowledged by the submitter’s system. In the non-persistent model, the inbound connection is opened by the submitter’s system and closes when all messages have been sent. The outbound connection is closed by the interface when all messages have been sent and opened again when new messages are available.
The processing of patient demographic messages is synchronous. Supported message formats include HL7 2.X.