Download the PHP package laratusk/spreedly without Composer

Spreedly PHP SDK

A production-ready PHP SDK for the Spreedly payment orchestration API, following the Stripe PHP SDK architecture. Works as a standalone PHP library or as a Laravel package.

Requirements

• PHP ^8.2
• Laravel ^10.0 || ^11.0 || ^12.0 (optional)

Installation

Standalone PHP Usage

Configuration Options

Laravel Usage

Publish the config file:

Add credentials to your .env:

Use the facade:

Or inject the client:

Certificate Automation (Laravel)

Spreedly supports certificate pinning for additional API security. The SDK can automatically generate, upload, and renew self-signed certificates on a per-machine basis, binding each certificate to the machine's MAC address so that multi-server deployments each maintain their own certificate.

Setup

Publish and run the migration:

Add the relevant variables to your .env:

How it works

Each server keeps exactly one active certificate at a time, identified by its MAC address. The key pair is generated locally (the private key never leaves the server), then uploaded to Spreedly. The encrypted private key is stored in your database.

Artisan command

Scheduled auto-renewal

Register the command in your scheduler so certificates are renewed automatically. Running it once a day is sufficient — the command exits immediately when the certificate is not close to expiring.

Laravel 11+ (routes/console.php):

Laravel 10 (app/Console/Kernel.php):

Tip: Set SPREEDLY_CERTIFICATE_EXPIRING_DAYS to control how many days before expiry a renewal is triggered. The default is 7.

Resolving the current certificate

Retrieve the active certificate for the current machine at runtime:

Resources

Gateways

Docs: Gateways API

Payment Methods

Docs: Payment Methods API

Transactions

Docs: Transactions API

Note: All monetary amounts are in the smallest currency unit (cents for USD). 1000 = $10.00.

Receivers

Docs: Receivers API

Certificates

Docs: Certificates API

Environments

Docs: Environments API

Events

Docs: Events API

Merchant Profiles

Docs: Merchant Profiles API

Composer (Workflows)

Docs: Composer API

SCA Authentication

Docs: SCA Authentication API

Sub Merchants

Docs: Sub Merchants API

Card Refresher

Docs: Card Refresher API

Keeps stored payment methods up-to-date by fetching the latest card details from card networks.

Claim

Docs: Claim API

Payments

Docs: Payments API

Protection Events

Docs: Protection Events API

Protection events are created when Spreedly detects a change to a stored payment method (e.g. updated card number or expiration date).

Access Secrets (Environments)

Docs: Access Secrets API

Network Tokenization (Payment Methods)

Docs: Network Tokenization API

Payment Method Events

Docs: Payment Method Events API

Protection Provider & SCA Provider (Merchant Profiles)

Docs: Merchant Profiles API

Pagination

Spreedly uses token-based pagination (since_token). The SDK provides a PaginatedCollection that handles this:

Error Handling

All exceptions extend SpreedlyException and provide:

• $e->getMessage() — Human-readable message
• $e->httpStatus — HTTP status code
• $e->errors — Array of validation errors (for 422)
• $e->spreedlyErrorKey — Spreedly error key (e.g., errors.not_found)

Custom HTTP Transport

Implement TransporterInterface to use a custom HTTP client:

Testing

Testing in Your Application

The SDK ships with SpreedlyFake and MockTransporter to make testing easy — no real HTTP calls, no Spreedly credentials needed.

Standalone PHP

Laravel (swap the container binding)

In your Laravel feature tests, swap the SpreedlyClient binding before the code under test runs. After the swap the Spreedly facade automatically uses the fake.

Or test the facade directly:

MockTransporter API

Running the SDK's Own Tests

Run tests:

Run quality checks:

Integration Tests

Integration tests require real Spreedly credentials and run against the test gateway:

License

MIT. See LICENSE.md.