search

hps / heartland-php

Heartland Payment Systems Payment Gateway PHP SDK
https://developer.heartlandpaymentsystems.com/SecureSubmit/
GNU General Public License v2.0
25 stars 23 forks source link

readme

Heartland logo

Heartland PHP SDK

This SDK makes it easy to integrate your PHP application with Heartland’s Portico Gateway API, as well as other APIs such as MasterPass. Additionally, this SDK also facilitates integration with Heartland Secure: Out-of-Scope devices, providing for simple semi- integrated EMV acceptance, enabling a true single point of integration for omni-channel developers.

Supported features include:

Data Security API Reference Testing &
Certification		 API Keys Links
Register an Account
Partner with Heartland

Developer Support

You are not alone! If you have any questions while you are working through your development process, please feel free to reach out to our team for assistance!

Installation

Add this SDK to your PHP project and require it once.

<?php
require_once 'Hps.php';
?>

Using Composer? Require this library in your composer.json:

{
    "require": {
        "hps/heartland-php": "*"
    }
}

and run composer update to pull down the dependency and update your autoloader.

API Keys

Integrations that use card not present transactions, such as eCommerce web applications, will use API keys to authenticate. There are exceptions, such as card present POS integrations. For these projects please contact us for more information.

To begin creating test transactions you will need to obtain a set of public and private keys. These are easily obtained by creating an account on our developer portal. Your keys are located under your profile information.

Developer Keys

You will use your public key when implementing card tokenization and your private key will be used when communicating with our Portico Gateway. More details can be found in our documentation.

Note: Multi-Use tokenization is not enabled by default when creating an account. You can contact Heartland's Specialty Products Team to have this enabled. This is also true if you wish to use Gift & Loyalty, ACH, and Debit.

Data Security

If your app stores, processes, or transmits cardholder data in cleartext then it is in-scope for PA-DSS. If your app is hosted, or the data in question otherwise comes into your organization, then the app and your entire company are in-scope for PCI DSS (either as a merchant or a service provider). Heartland offers a suite of solutions to help keep integrators' applications and/or environments shielded from cardholder data, whether it motion or at rest.

To summarize, when you create a paymentMethod using this SDK you have the following options for securely avoiding interaction with sensitive cardholder data:

Documentation and Examples

You can find the latest SDK documentation along with code examples on our Developer Portal. In addition you can find many examples in the SDK itself, located under the examples directory:

Quick Tip: The included test suite can be a great source of code samples for using the SDK!

Fluent Interface

Note that our SDK provides a Fluent Interface which allows you to replace a charge call that looks like this:

 $response = $chargeSvc->charge(17.01, "usd", TestCreditCard::validVisaCreditCard(), TestCardHolder::certCardHolderShortZip());

With one that reads like this:

 $response = $this->service
                  ->charge()
                  ->withAmount(17.01)
                  ->withCurrency("usd")
                  ->withCard(TestCreditCard::validVisaCreditCard())
                  ->withCardHolder(TestCardHolder::certCardHolderShortZip())
                  ->execute();

Between the two samples you can more easily read and understand what the code is doing in the second example than the first. That is a big advantage and helps speed development and reduce errors when using methods that allow a large number of parameters.

Quick Tip: You will find Fluent and Non-Fluent examples in the included test suite.

Testing & Certification

Testing your implementation in our Certification/Sandbox environment helps to identify and squash bugs before you begin processing transactions in the production environment. While you are encouraged to run as many test transactions as you can, Heartland provides a specific series of tests that you are required to complete before receiving Certification. Please contact Heartland to initiate certification for your integration. For eComm integrations please email our Specialty Products Team, for POS developers please email Integrations.

Quick Tip: You can get a head start on your certification by reviewing the certification tests in the included test suite.

Test Card Data

The following card numbers are used by our Certification environment to verify that your tests worked. Note that while variations (such as 4111111111111111) will work for general testing the cards listed below are required to complete certification. For card present testing Heartland can provide you with EMV enabled test cards.

Name Number Exp Month Exp Year CVV Address Zip
Visa 4012002000060016 12 2025 123 6860 Dallas Pkwy 75024
MasterCard 5473500000000014 12 2025 123 6860 Dallas Pkwy 75024
Discover 6011000990156527 12 2025 123 6860 Dallas Pkwy 75024
Amex 372700699251018 12 2025 1234 6860 Dallas Pkwy 75024
JCB 3566007770007321 12 2025 123 6860 Dallas Pkwy 75024

Testing Exceptions

During your integration you will want to test for specific issuer responses such as 'Card Declined'. Because our sandbox does not actually reach out to card brands for authorizations we have devised specific transaction amounts that will trigger issuer response codes and gateway response codes. Please contact Heartland for a complete listing of values you can charge to simulate AVS, CVV and Transaction declines, errors, and other responses that you can catch in your code:

     try
            {
                 $response = $this->service
                                  ->charge()
                                  ->withAmount(5)
                                  ->execute();
            }
            catch (HpsInvalidRequestException $e)
            {
                // handle errors for invalid arguments such as a charge amount less than zero dollars
            }
            catch (HpsAuthenticationException $e)
            {
                // handle errors related to your HpsServiceConfig (username, pw, api keys etc.)
            }
            catch (HpsCreditException $e)
            {
                // handle card-related exceptions: card declined, processing error, etc                 
            }

Contributing

All our code is open sourced and we encourage fellow developers to contribute and help improve it!

  1. Fork it
  2. Create your feature branch (git checkout -b my-new-feature)
  3. Ensure SDK tests are passing
  4. Commit your changes (git commit -am 'Add some feature')
  5. Push to the branch (git push origin my-new-feature)
  6. Create new Pull Request

Included Test Suite

The included test suite can help ensure your contribution doesn't cause unexpected errors and is a terrific resource of working examples that you can reference.

Clone this repository locally, install dependencies with Composer, and run PHPUnit against the provided tests.

$ git clone https://github.com/SecureSubmit/heartland-php.git
$ cd heartland-php
$ composer install
$ php vendor/bin/phpunit -c tests/phpunit.xml

This will run through all of our test suites by default. To run a single test suite, pass the --testsuite option to php vendor/bin/phpunit with one of the following values:

Example:

$ php vendor/bin/phpunit -c tests/phpunit.xml --testsuite certification