Summary

Credit card transactions are a major component of any payment collection features in athenaNet, and API users should thoroughly test their applications for compatibility with athenahealth’s APIs for processing credit card-related transactions. This document guides API users in helping ensure that both practices and API users have a successful experience in utilizing the credit card APIs. Basic functionality covers all aspects of the API not involving contract setup. A separate section below covers contract testing.

Configuration

By using the POST /patients/{patientid}/recordpayment endpoint, you may record payments via API (see Record Payment). In order to support recording non-CCP credit card payments via API, we introduce the following new API.

This API retrieves a list of valid, non-deleted credit card methods that have been configured at a practice level so the API user can determine which credit card payment methods are valid for a practice. 

The following criteria can optionally be supplied when calling this new endpoint:

• limit - the number of entries to return (default 1500, max 5000)
• offset - the starting point of entries; 0-indexed

Output fields include paired combinations of name and paymentmethod.  API users will supply the paymentmethod value when calling 

Sample Data:

• "name" : "American Express",
• "paymentmethod" : "AMEX"

 

NOTE: This page is a summary of payment testing. More detailed information is available for users whose companies have signed a non-disclosure agreement (NDA) with athenahealth.

Normal Transactions

Validation of the basic functionality entails performing a series of tests to make sure that your solution is working properly with athenaNet. Each of the following should be performed separately with a VISA and an AMEX card (even if the practice does not support AMEX, in which case the purchase should fail gracefully). If possible, separate testing with one of each of the other two types of major cards (DISC/MC) is also encouraged.

Perform a standard keyed & swipe purchase with the card on a test patient, typically with a small amount, such as $0.05. Note: Swipe purchases cannot easily be tested in preview unless you have a dummy test card from some source (see note below about which test cards should be used in which environments). In the preview environment, you may use the following test card data:

Card Type:

Visa

Card #	4000 0000 0000 0002   and 4012 8888 8888 1881
Expiration Date	12/22
Dollar amount	Must end in .00, ex: 40.00 but not 40.32

MasterCard

Card #	5121 2121 2121 2124
Expiration Date	12/22
Dollas amount	Must end in .00, ex: 40.00 but not 40.32

Discover

Card #	6011 0000 0000 0004
Expiration Date	12/22
Dollar amount	Must end in .00, ex: 40.00 but not 40.32

American Express

Card #	371449635398431
Expiration Date	12/22
Dollar amount	Must end in .00, ex: 40.00 but not 40.32

 

 

OR

 

 

You may use the following sample track data.

Be careful with URL encoding since the initial % in the data needs to become %25:

 

 

Card Type:

 

 

Visa

Sample Track Data	%B4124939999999990^TEST/TESTCARD^19129015432139614567891234567890?;4124939999999990=191290154321396145?
Track 1 Length	70
Track 2 Length	35

 

MasterCard

Sample Track Data	%B5472063333333330^TEST/TESTCARD^19129015432139614567891234567890011223?;5472063333333330=19129015432139614567?
Track 1 Length	76
Track 2 Length	37

 

Discover

Sample Track Data	%B6011013333333331^TEST/TESTCARD^19129015432139614567891234567890011223?;6011013333333331=19129015432139614567?
Track 1 Length	76
Track 2 Length	37

 

American Express

Sample Track Data	%B370000999999990^TEST/TESTCARD^19129015432139614567891234567890011223?;370000999999990=19129015432139614567?
Track 1 Length	75
Track 2 Length	36

 

Important Notes:

1. Ensure that your application …
   1. Retrieves a receipt from athenaNet for the transaction.
   2. Asks the patient to sign it digitally.
   3. Returns the signed PDF copy to athenaNet (via the API).
2. Ensure the receipt can be viewed in the athenaNet UI.
3. Ensure the payment processed successfully and was posted properly via athenaNet UI.
4. Void the transaction in athenaNet (thereby refunding your card, if using a real one in production).

Dos and Don’ts

Please do:

• Test your solution in the preview environment (/preview1/) before moving to testing in our production environment (/v1).
• Aggressively test edge cases (preferably in preview first), such as network connection loss mid-transaction, or mid-workflow. 
• Perform any additional tests beyond the basics that you feel necessary for your solution.
• Engage directly with your early rollout practices to help ensure successful testing. You may need their help in performing some validation testing in production. Explain to them that this testing may incur minor extra credit card transaction fees (per transaction). 

Please do NOT:

• Use any "test cards" you may have from credit card processors (or other sources) in our production environment. 
• Use any real credit cards in the preview environment. This environment is not PCI-secure.

NOTE: The following is a table showing which types of cards should be tested in which environments:

Card Type	Preview	Production
Test cards	OK	Do not use
athenahealth-provided keyed card numbers	OK	Do not use
Real credit cards	Do not use	OK

 

Error/Exception Handling

In addition to testing the basic functionality, API users should also check to ensure that their solution correctly handles error messages and situations. Some of the most common situations are listed below, with testing suggestions.  

Note: The below list is not comprehensive since the responses can be different depending on card brands, processers/gateways, etc.  API users should take a "black box" approach when testing their solution.

Transaction Declined: A transaction can be declined for various reasons, including an invalid credit card number and/or expiration dates. API users should test these cases to make sure their system responds appropriately. Some of these responses can be simulated in the test environment by entering certain amounts. We suggest using these amounts in preview only:

-$1.05 – Will produce a DECLINED response for all card types

-$1.12 – Will produce a CALL AUTH CENTER response for all card types

-$1.14 – Will produce an INVALID CARD response for all card types except DISC (which returns CALL AUTH CENTER)

-$1.33 – Will produce an EXPIRED CARD response for all card types except DISC (which returns CALL AUTH CENTER)

Transaction Timeouts:  This class of error indicates a connection breakdown, either of the API user-to-athena type or of the athena-to-Transaction Processor type.

The former situation can be simulated easily by “pulling the plug” on the device’s internet connection mid-transaction (preferably in athenaNet’s preview environment).

In the latter case your application would expect to receive an error response that says “Gateway Timeout”. It is not currently possible to test this timeout mode in our preview environment.

Additional VISA codes for testing: Please reference the codes below for VISA card testing. For example, if you were to submit a $1.00 amount, it will produce an APPROVAL response for VISA card types.  

Cents	Authorization Response
00	APPROVAL
01	CALL AUTH CENTER
04	PICK UP CARD
05	DECLINED
13	AMOUNT ERROR
14	INVALID CARD
19	PLEASE RETRY5270
33	EXPIRED CARD

 

Note: When testing the functionality in a preview environment you may receive the error: 

Error: There is no valid terminal ID associated with this department.

If you receive this error when testing in a dedicated preview environment, please work with your athenahealth technical resource to resolve this issue.