PHPackages                             hypercharge/hypercharge-php - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [API Development](/categories/api)
4. /
5. hypercharge/hypercharge-php

ActiveLibrary[API Development](/categories/api)

hypercharge/hypercharge-php
===========================

Hypercharge PHP Library / SDK

1.25.6(10y ago)23.5k2[6 issues](https://github.com/hypercharge/hypercharge-php/issues)[1 PRs](https://github.com/hypercharge/hypercharge-php/pulls)MITPHPPHP >=5.3

Since Jun 18Pushed 9y ago10 watchersCompare

[ Source](https://github.com/hypercharge/hypercharge-php)[ Packagist](https://packagist.org/packages/hypercharge/hypercharge-php)[ RSS](/packages/hypercharge-hypercharge-php/feed)WikiDiscussions master Synced yesterday

READMEChangelog (1)Dependencies (3)Versions (14)Used By (0)

hypercharge-php
===============

[](#hypercharge-php)

PHP SDK for the Hypercharge payment gateway.

[![Latest Stable Version](https://camo.githubusercontent.com/5980dce4e85d239a8fbf2239fda793fd6640b06b5dde846fd48f8235a6fb9abd/68747470733a2f2f706f7365722e707567782e6f72672f68797065726368617267652f68797065726368617267652d7068702f762f737461626c652e706e67)](https://packagist.org/packages/hypercharge/hypercharge-php)[![Build Status](https://camo.githubusercontent.com/fed28e5bc8471620ca664c01f046dda94f63facdaafdae4bde90a137ad39df8b/68747470733a2f2f7472617669732d63692e6f72672f68797065726368617267652f68797065726368617267652d7068702e706e67)](https://travis-ci.org/hypercharge/hypercharge-php)

tested with PHP > 5.3 on OSX/Linux

Matches [hypercharge-API-doc](https://github.com/hypercharge/hypercharge-api-doc) version 2.24 2014/09/16

Installation
------------

[](#installation)

Do not download the Hypercharge PHP SKD files manually. The php package manger [composer](http://getcomposer.org/) takes care of that.

Let's say `MY_PROJECT/` is your project root folder.

Do the following three steps:

1. [Download composer.phar](http://getcomposer.org/download/) to `MY_PROJECT/composer.phar`
2. With your text editor create a `MY_PROJECT/composer.json` containing

```
{
  "require": {
    "php": ">=5.3",
    "hypercharge/hypercharge-php": "*"
  }
}
```

This will tell composer to install the most recent Hypercharge PHP SDK version.

3. in the shell (DOS console or terminal) go to `MY_PROJECT/` and run the command

```
$ php composer.phar install
```

This downloads and installs Hypercharge PHP SDK and its dependencies into `MY_PROJECT/vendor/`.

Show what has been installed

```
$ php composer.phar show --installed
hypercharge/hypercharge-php    1.25.5 Hypercharge PHP Library / SDK
hypercharge/hypercharge-schema 1.25.2 Hypercharge API JSON Schema
hypercharge/json-schema-php    1.3.3  A library to validate a json schema.
```

nice.

Notice: Later, when deploying your project to your server, upload the complete `MY_PROJECT/vendor/` directory as well. `MY_PROJECT/vendor/` contains the installed packages and autoload files.

Configuration
-------------

[](#configuration)

To get started, add one of the following snippets to your global configuration file.

### Sandbox (for testing)

[](#sandbox-for-testing)

Hypercharge support creates a test-account and sends you login and password. For development and testing. No real money is transfered.

```
// config.php
require_once dirname(__DIR__).'/vendor/autoload.php';
Hypercharge\Config::set(
   'YOUR-MERCHANT-TEST-LOGIN'
  ,'YOUR-MERCHANT-TEST-PASSWORD'
  ,Hypercharge\Config::ENV_SANDBOX
);
```

### Live

[](#live)

When your Hypercharge boarding is complete our support team will send you your live login and password. Real money transactions here!

```
// config.php
require_once dirname(__DIR__).'/vendor/autoload.php';
Hypercharge\Config::set(
   'YOUR-MERCHANT-LOGIN'
  ,'YOUR-MERCHANT-PASSWORD'
  ,Hypercharge\Config::ENV_LIVE
);
```

If there is no `MY_PROJECT/vendor/autoload.php` in your project follow the [installation instructions](#installation).

Credit Card sale Transaction
----------------------------

[](#credit-card-sale-transaction)

Submit 77.00 USD as a credit card sale to hypercharge channel.

Note: You have to be [PCI compliant](https://en.wikipedia.org/wiki/Payment_Card_Industry_Data_Security_Standard) to handle Credit Card data. Most likely you are not PCI compliant, in that case you use our [Web Payment Form](#web-payment-form-wpf-session) or our [Mobile Payment](#create-mobile-payment-session).

```
require_once 'config.php';

// see field 'currency'
$channelToken = 'YOUR-USD-CHANNEL-TOKEN';

$sale = Hypercharge\Transaction::sale($channelToken, array(
  'currency'          => 'USD'
  ,'amount'           => 7700 // in cents, must be int
  ,'transaction_id'   => 'YOUR-GENERATED-UNIQUE-ID' // TODO your order-id here
  ,'usage'            => 'Appears in the customers bank statement'
  ,'card_holder'      => 'Max Mustermann'
  ,'expiration_month' => '07'
  ,'expiration_year'  => '2018'
  ,'card_number'      => '4200000000000000'
  ,'cvv'              => '123'
  ,'customer_email'   => 'max@mustermann.de'
  ,'customer_phone'   => '+403012345678'

  // TODO: dummy for cli run only. remove!
  ,'remote_ip'        => '127.0.0.1'
  // TODO: uncomment
  //,'remote_ip'        => $_SERVER['REMOTE_ADDR']

  ,"billing_address" => array(
      "first_name" =>"Max",
      "last_name"  =>"Mustermann",
      "address1"   =>"Muster Str. 12",
      "zip_code"   =>"10178",
      "city"       =>"Berlin",
      "country"    =>"DE"
  )
));

if($sale->isApproved()) {
  // cc transaction successfull
} else {
  //
}
```

To see local validation errors wrap the `Hypercharge\Transaction::sale` call in a `try catch`.

```
require_once 'config.php';

$channelToken = 'YOUR-USD-CHANNEL-TOKEN';
try {
  $sale = Hypercharge\Transaction::sale($channelToken, array(
    'currency'          => 'USD'
    ,'amount'           => 7700 // in cents, must be int
    ,'transaction_id'   => 'YOUR-GENERATED-UNIQUE-ID' // TODO your order-id here
    ,'usage'            => 'Appears in the customers bank statement'
    ,'card_holder'      => 'Max Mustermann'
    ,'expiration_month' => '07'
    ,'expiration_year'  => '2018'
    ,'card_number'      => '4200000000000000'
    ,'cvv'              => '123'
    ,'customer_email'   => 'max@mustermann.de'
    ,'customer_phone'   => '+403012345678'
    ,'remote_ip'        => $_SERVER['REMOTE_ADDR']
    ,"billing_address" => array(
        "first_name" =>"Max",
        "last_name"  =>"Mustermann",
        "address1"   =>"Muster Str. 12",
        "zip_code"   =>"10178",
        "city"       =>"Berlin",
        "country"    =>"DE"
    )
  ));

  if($sale->isApproved()) {
    echo "cc transaction successfull\n";
    print_r($sale);
  } else {
    echo "cc transaction FAILED\n";
    print_r($sale);
  }
} catch(Hypercharge\Errors\ValidationError $e) {
  echo "local validation errors\n";
  print_r( $e->errors );

} catch(Exception $e) {
  echo "severe error\n";
  print_r($e);
}
```

Web Payment Form (WPF) session
------------------------------

[](#web-payment-form-wpf-session)

The following example is more complex.

- create a WPF session.
- redirect customer browser to WPF url provided
- customer submits WPF and is redirected to return\_success\_url you provided. In the mean time hypercharge notifies your backend by calling `notification_url`, providing the payment status.

```
require_once 'config.php';

try {
  // create the WPF payment session
  $payment = Hypercharge\Payment::wpf(array(
    'currency' => 'EUR'
    ,'amount' => 1000 // in cents
    ,'transaction_id' => 'YOUR-GENERATED-UNIQUE-ID' // TODO replace with your e.g. order id
    ,'description' => 'Appears as intro text in the WPF form'
    ,'usage' => 'Appears in the customers bank statement'

    // TODO: set your PaymentNotification handler url here
    ,'notification_url' => 'https://your-server.com/hypercharge-wpf-notifications.php'

    // TODO: set your return pages for the user here. These are the pages he is shown after leaving the WPF
    ,'return_success_url' => 'http://your-server.com/payment-return-page.php?status=success'
    ,'return_failure_url' => 'http://your-server.com/payment-return-page.php?status=failure'
    ,'return_cancel_url'  => 'http://your-server.com/payment-return-page.php?status=cancel'

    ,'billing_address' => array(
        'first_name' =>'Max',
        'last_name'  =>'Mustermann',
        'address1'   =>'Muster Str. 12',
        'zip_code'   =>'10178',
        'city'       =>'Berlin',
        'country'    =>'DE'
    )
  ));

  if($payment->shouldRedirect()) {
    // ok, WPF session created.

    // TODO: pseudocode, comment or replace with your own business logic!
    store_hypercharge_payment_unique_id_to_your_order( $payment->unique_id );

    // redirect user to WPF
    header('Location: '. $payment->getRedirectUrl());

  // handle errors...
  } elseif($payment->isPersistentInHypercharge()) {
    // payment has been created in hypercharge but something went wrong.

    // TODO: pseudocode, comment or replace with your own business logic!
    store_hypercharge_payment_unique_id_to_your_order( $payment->unique_id );

    // 1.) check $payment->error (a subclass of Hypercharge\Errors\Error)
    //     and show error message to customer
    // 2.) manually login to hypercharge merchant backend.
    //     Go to "Payments", search by unique_id and analize the log messages.

  } else {
    // TODO handle error
    // authentication error? check $login, $password
    // inputdata error? check your php code for missing or misspelled fields.

  }

} catch(Hypercharge\Errors\ValidationError $e) {
  // no payment created in hypercharge because of local pre-validation errors

  // show validation errors to customer
  // $e->errors is an Array of Hash, format: [ { "property": String , "message" : String }, ... ]

} catch(Exception $e) {
  // severe error
  // log $e
  // display apologies to customer
}
```

The WPF is displayed in English by default (`'en'`). If you want a German WPF simply change the redirection line to:

```
    header('Location: '. $payment->getRedirectUrl('de'));
```

WPF PaymentNotification
-----------------------

[](#wpf-paymentnotification)

With a PaymentNotification Hypercharge notifies your server about a Payment status change e.g. when a Payment was successfull (status `approved`) or has failed in some way. A PaymentNotification is a server to server request in the background. Neither webbrowser nor user interaction is involved.

```
hypercharge                 your-server.com/hypercharge-wpf-notifications.php
    |   -> http POST request: notification ->   |
    |                                           |     -> store notification status to your DB
    |                                           |     -> e.g. trigger shipping (sucess) or send failure email to user (NOT success)
    |   isVerified()) {
  $payment = $notification->getPayment();
  if($notification->isApproved()) {

    ////////////////////////////////////////
    // payment successfull
    // implement your business logic here
    ////////////////////////////////////////

  } else {

    ////////////////////////////////////////
    // payment NOT successfull
    // check $payment->status
    // implement your business logic here
    ////////////////////////////////////////

  }

  // http response.
  // Tell hypercharge the notification has been successfully processed
  // and ensure output ends here
  die( $notification->ack() );

} else {
  // signature invalid or message does not come from hypercharge.
  // check your configuration or notificatoin request origin
}
```

See [PaymentNotification](https://github.com/hypercharge/hypercharge-php/blob/master/lib/Hypercharge/PaymentNotification.php) class definition for how to use `$notification` or `$payment`.

An example with symbolic busineslogic as pseudocode:

```
require_once 'config.php';

$notification = Hypercharge\Payment::notification($_POST);
if($notification->isVerified()) {
  $payment = $notification->getPayment();
  if($notification->isApproved()) {

    ////////////////////////////////////////
    // payment successfull
    // implement your business logic here

    // example as pseudocode, replace with your own code...

    // store notification status to your database
    // Notice: to be 100% racecondition proof update status to 'payment_approved' has to be done atomically
    $updatedRows = update_order(array(
      'set'   => array('status'=> 'payment_approved'),
      'where' => array('status'=> 'waiting_for_payment_approval'
                      ,'hypercharge_unique_id' => $payment->unique_id
      )
    ));

    if($updatedRows == 1) {
      // ok, start shipping
      $order = find_order_where(array('status' => 'payment_approved'
                                      ,'hypercharge_unique_id' => $payment->unique_id
      ));
      $order->ship_goods_to_customer();

    } else {
      // hypercharge notification already received! ignore duplicate notification.
    }
    //
    // END of your business logic
    ////////////////////////////////////////

  } else {

    ////////////////////////////////////////
    // payment NOT successfull
    // check $payment->status and handle it

    // ...

    // END of your business logic here
    ////////////////////////////////////////

  }

  // Tell hypercharge the notification has been successfully processed
  // and ensure output ends here
  die( $notification->ack() );

} else {
  // signature invalid or message does not come from hypercharge.
  // check your configuration or notificatoin request origin
}
```

Create Mobile Payment Session
-----------------------------

[](#create-mobile-payment-session)

Mobile Payments are quite similar to WPF Payments. The Session creation has slightly different data. The Notification code is the same as WPF Notification abough.

your\_server -> POST XML -> hypercharge

```
require_once 'config.php';

try {
  // create the mobile payment session
  $payment = Hypercharge\Payment::mobile(array(
    'currency' => 'EUR'
    ,'amount' => 1000 // in cents
    ,'transaction_id' => 'YOUR-GENERATED-UNIQUE-ID'
    ,'usage' => 'Appears in the customers bank statement'
    ,'notification_url' => 'https://your-server.com/hypercharge-wpf-notifications.php'
  ));

  if($payment->shouldContinueInMobileApp()) {
    // ok, mobile payment session created.

    save_payment_unique_id_to_order($payment->unique_id);

    // tell your mobile device where to
    // a) submit credit card xml data to (submit_url)
    // b) cancel the payment if user presses 'cancel' in your mobile app (cancel_url)
    // see example below.
    die(json_encode($payment));

  } else {

    // TODO handle error
    // vaildation
    // authentication error -> check $login, $password
    // inputdata error -> check your php code for missing
    // or misspelled fields in $paymentData

  }
} catch(Hypercharge\Errors\Error $e) {
  // no payment created in hypercharge because of local pre-validation errors

  // check your php code
  // display apologies to customer "Sorry, no payment possible at the moment."
}
```

Submit Mobile Payment from mobile device
----------------------------------------

[](#submit-mobile-payment-from-mobile-device)

Example Mobile Submit XML your mobile application posts to `$payment->submit_url` to process the payment.

```

  credit_card
  Manfred Mann
  4200000000000000
  123
  2015
  12

```

If you're concerned of POSTing cc data via internet: The `$payment->submit_url` will look something like `https://testpayment.hypercharge.net/mobile/submit/eabcb7a41044e764746b0c7e32c1e9d1` so the xml will be transmitted encrypted.

Tests
-----

[](#tests)

Running tests for hypercharge-php itself has to be done outside of `MY_PROJECT`. Clone hypercharge-php into its own directory

```
git clone https://github.com/hypercharge/hypercharge-php.git
```

step into the directory

```
cd hypercharge-php
```

install composer (here 1.0.0-alpha7 feel free to use a more recent one)

```
curl -o composer.phar http://getcomposer.org/download/1.0.0-alpha7/composer.phar
```

install dev dependecies

```
php composer.phar update --dev
```

### Unit Tests

[](#unit-tests)

Run the unit tests

```
php test/all.php
```

You might wonder what the output means:

```
File does not exist /home/hans/hypercharge-php/test/credentials.json. See README.md chapter 'Remote Tests' how to setup credentials for testing.
```

Simply read the next chapter.

### Remote Tests

[](#remote-tests)

The remote tests make https calls to the hypercharge sandbox (testing gateway).

At first you have to setup your login and channel tokens:

Copy `test/credentials.json.example` to `test/credentials.json`. You received credentials when hypercharge created your test-acount. Add the credentials to `test/credentials.json`. See values marked with `TODO`.

Run the remote tests

```
php test/remote.php
```

this will take about a minute.

You can use environment variables:

```
DEBUG=1 CREDENTIALS=development php test/remote.php
```

- `DEBUG=1` verbose output.
- `CREDENTIALS=development` switch to "development" credentials. Default is `sandbox`

Note:

- `test/credentials.json` should not be checked into your code repository. e.g. add it to `.gitignore`
- Do not run the remote tests on your live credentials.

Warranty
--------

[](#warranty)

This software is provided "as is" and without any express or implied warranties, including, without limitation, the implied warranties of merchantibility and fitness for a particular purpose.

###  Health Score

28

—

LowBetter than 52% of packages

Maintenance0

Infrequent updates — may be unmaintained

Popularity21

Limited adoption so far

Community16

Small or concentrated contributor base

Maturity65

Established project with proven stability

 Bus Factor1

Top contributor holds 93.9% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~75 days

Recently: every ~130 days

Total

13

Last Release

3852d ago

Major Versions

1.24.3 → 2.x-dev2013-09-10

### Community

Maintainers

![](https://www.gravatar.com/avatar/557783835d883292084965c829938913bebbbd9f6289673e23e78b40c4139d73?d=identicon)[hypercharge](/maintainers/hypercharge)

---

Top Contributors

[![janmentzel](https://avatars.githubusercontent.com/u/363563?v=4)](https://github.com/janmentzel "janmentzel (46 commits)")[![larisagroza](https://avatars.githubusercontent.com/u/8049178?v=4)](https://github.com/larisagroza "larisagroza (1 commits)")[![mdkroyer](https://avatars.githubusercontent.com/u/6824719?v=4)](https://github.com/mdkroyer "mdkroyer (1 commits)")[![vierbergenlars](https://avatars.githubusercontent.com/u/1194648?v=4)](https://github.com/vierbergenlars "vierbergenlars (1 commits)")

---

Tags

apisdkpaymenthypercharge

### Embed Badge

![Health badge](/badges/hypercharge-hypercharge-php/health.svg)

```
[![Health](https://phpackages.com/badges/hypercharge-hypercharge-php/health.svg)](https://phpackages.com/packages/hypercharge-hypercharge-php)
```

###  Alternatives

[blocktrail/blocktrail-sdk

The BlockTrail PHP SDK, for integration of Bitcoin functionality through the BlockTrail API

4921.1k3](/packages/blocktrail-blocktrail-sdk)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)