README

A Composer-installable, PSR-4 autoloaded package for the official Cardstream Payment Gateway PHP SDK, with a plug-and-play Laravel integration (auto-discovered ServiceProvider, Facade, and config/cardstream.php) layered on top. Works standalone in any core PHP 7.4+/8.x codebase with zero Laravel dependency.

The upstream SDK ships as a single gateway.php file meant to be manually require'd. This package repackages the same \P3\SDK\Gateway class so it can be installed and autoloaded via Composer, and published to Packagist for the community.

The SDK logic itself is unmodified from Cardstream's official release, other than guarding a few $_SERVER lookups so the SDK doesn't emit PHP warnings when called outside a live HTTP request (Artisan commands, queued jobs, tests) — see CHANGELOG.md. This project's primary job is Composer/PSR-4 packaging around it.

Installation
Prerequisites
Usage (core PHP)
Laravel Integration
Configuration Reference
Testing
License
Disclaimer

Installation

composer require hafizasifali/cardstream-php-sdk

Nothing else to wire up: in a Laravel app the CardstreamServiceProvider and Cardstream facade are auto-discovered via Composer's extra.laravel metadata (no manual config/app.php edits needed). In a plain PHP project P3\SDK\Gateway is available as soon as vendor/autoload.php is loaded — the Laravel classes simply aren't touched.

Prerequisites

PHP 7.4+ (tested on PHP 7.4 through 8.5)
ext-curl (falls back to PHP stream wrappers if unavailable)
HTTPS enabled on your server for direct integration (the gateway responds over SSL)
Laravel integration additionally requires illuminate/support — already present in any Laravel 8–12 app, nothing extra to install

Usage (core PHP)

Set your Merchant ID and secret before making a request:

require 'vendor/autoload.php';

use P3\SDK\Gateway;

Gateway::$merchantID = '100856';
Gateway::$merchantSecret = 'YourMerchantSecretHere';

Direct Integration

$request = [
    'merchantID'       => 100001,
    'action'           => 'SALE',
    'type'             => 1,
    'currencyCode'     => 826,
    'countryCode'      => 826,
    'amount'           => 1001,
    'cardNumber'       => '4012001037141112',
    'cardExpiryMonth'  => 12,
    'cardExpiryYear'   => 25,
    'cardCVV'          => '083',
    'customerName'     => 'Test Customer',
    'customerEmail'    => 'test@testcustomer.com',
    'customerAddress'  => '16 Test Street',
    'customerPostCode' => 'TE15 5ST',
    'orderRef'         => 'Test purchase',
    // Required for 3DSv2 direct integration
    'remoteAddress'      => $_SERVER['REMOTE_ADDR'],
    'threeDSRedirectURL' => $pageUrl . '&acs=1',
];

try {
    $response = Gateway::directRequest($request);
    // Inspect $response['responseCode'] / $response['responseMessage']
} catch (\Exception $e) {
    // Handle communication or signature errors
    echo $e->getMessage();
}

Hosted Integration

echo Gateway::hostedRequest($request);
// Renders an auto-submitting HTML form that redirects the
// customer to the Cardstream hosted payment page.

On the return page, verify the response:

try {
    Gateway::verifyResponse($_POST);
} catch (\Exception $e) {
    die($e->getMessage());
}

3DSv2 Browser Info

For 3DSv2 direct integration, collect the required browser fingerprint fields:

echo Gateway::collectBrowserInfo([
    'formData' => ['orderRef' => 'Test purchase'],
]);

Laravel Integration

The package auto-registers P3\SDK\Laravel\CardstreamServiceProvider and the Cardstream facade via Laravel's package discovery — just composer require it and configure via .env.

Configuration

Publish the config file if you want to edit it directly (optional — env vars alone are enough for most setups):

php artisan vendor:publish --tag=cardstream-config

Then set your credentials in .env:

CARDSTREAM_MERCHANT_ID=100856
CARDSTREAM_MERCHANT_SECRET=YourMerchantSecretHere
CARDSTREAM_MERCHANT_PASSWORD=
CARDSTREAM_HOSTED_URL=https://gateway.cardstream.com/hosted/
CARDSTREAM_DIRECT_URL=https://gateway.cardstream.com/direct/
CARDSTREAM_PROXY_URL=
CARDSTREAM_TIMEOUT=30
CARDSTREAM_DEBUG=false

Any of these left unset falls back to P3\SDK\Gateway's own defaults (Cardstream's public demo merchantID/merchantSecret — see the warning in Configuration Reference). The service provider applies your .env/config values to the underlying Gateway statics on boot, so both the facade and P3\SDK\Gateway directly stay in sync — use whichever style you prefer.

Usage via the Facade

use Cardstream;

$response = Cardstream::directRequest([
    'action'       => 'SALE',
    'type'         => 1,
    'currencyCode' => 826,
    'countryCode'  => 826,
    'amount'       => 1001,
    'cardNumber'   => '4012001037141112',
    // ...
]);

Usage via the container (for injection/mocking in tests)

use P3\SDK\Laravel\CardstreamGateway;

class CheckoutController
{
    /** @var CardstreamGateway */
    private $gateway;

    public function __construct(CardstreamGateway $gateway)
    {
        $this->gateway = $gateway;
    }

    public function pay()
    {
        return $this->gateway->directRequest([/* ... */]);
    }
}

Because CardstreamGateway is bound as a singleton in the container, it can be swapped for a test double with $this->mock(CardstreamGateway::class) in your Laravel feature tests without touching the underlying static SDK.

Both the facade and P3\SDK\Gateway::* calls are equivalent — the facade and the injectable CardstreamGateway class are thin, optional conveniences around the same static SDK.

Configuration Reference

Property	Default	Description
`Gateway::$hostedUrl`	`https://gateway.cardstream.com/hosted/`	Hosted API endpoint
`Gateway::$directUrl`	`https://gateway.cardstream.com/direct/`	Direct API endpoint
`Gateway::$merchantID`	`100001` (Cardstream's public demo account)	Merchant Account ID or Alias
`Gateway::$merchantPwd`	`null`	Merchant account password
`Gateway::$merchantSecret`	`Circle4Take40Idea` (Cardstream's public demo secret)	Merchant account secret (for signing)
`Gateway::$proxyUrl`	`null`	Optional outbound proxy URL
`Gateway::$timeout`	`30`	cURL/stream connect+transfer timeout, in seconds
`Gateway::$debug`	`false`	Log debug output via `error_log`

Do not ship to production without overriding $merchantID and $merchantSecret. Both default to Cardstream's public sandbox/demo credentials, not blank values — if you forget to set your own, requests will be signed with the demo secret and either fail against your live account or silently succeed against the sandbox instead of your account.

Useful response code constants: Gateway::RC_SUCCESS, Gateway::RC_DO_NOT_HONOR, Gateway::RC_NO_REASON_TO_DECLINE, Gateway::RC_3DS_AUTHENTICATION_REQUIRED.

See the class docblocks in src/Gateway.php for full method signatures, or Cardstream's integration guides for complete gateway field reference.

Testing

composer install
vendor/bin/phpunit

The suite covers:

Unit tests (tests/GatewaySignatureTest.php, tests/GatewayValidationTest.php) — signing, signature verification (full and partial), HTML field escaping, and prepareRequest() validation. No network access needed.
HTTP integration test (tests/GatewayHttpIntegrationTest.php) — spins up a local fake Gateway with PHP's built-in server and drives Gateway::directRequest() through a real cURL round trip (sign → POST → parse → verify), including the declined-transaction and signature-mismatch paths. This is what proves the package works plug-and-play out of the box, without needing a real Cardstream account.
Laravel tests (tests/Laravel/ServiceProviderTest.php, via Orchestra Testbench) — provider auto-discovery, config merging, .env/config values reaching the underlying Gateway statics, container binding, the facade, and vendor:publish.

CI (.github/workflows/tests.yml) runs the full suite on PHP 7.4–8.3.

License

Disclaimer

This is an independent, community-maintained Composer package. It is not an official Cardstream product. Cardstream only supports the SDK logic itself (the original gateway.php); use of this package requires full end-to-end testing by the integrator before production use.

hafizasifali / cardstream-php-sdk

Maintainers

Package info

Statistics

Security