README

A Laravel-native Adyen API client generated directly from Adyen's OpenAPI specifications.

This is an unofficial community package. It is not affiliated with or endorsed by Adyen.

Requires PHP 8.5, Laravel 13, and Guzzle 8.

The package does not depend on adyen/php-api-library. It provides a small shared HTTP runtime and generated PHP types for the newest numeric version of every specification family published in Adyen/adyen-openapi.

The pinned manifest currently contains 50 specification families: 31 callable APIs and 19 notification or Terminal model sets. Historical API versions are intentionally not included.

Installation

Install the package with Composer:

composer require laraworld/adyen

Configuration

Publish the configuration file:

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

For most integrations, configure one API key and your company-specific live URL prefix:

ADYEN_ENVIRONMENT=test
ADYEN_APP_NAME=my-application
ADYEN_API_KEY=your-api-key
ADYEN_LIVE_URL_PREFIX=your-live-url-prefix
ADYEN_REQUEST_TIMEOUT=30
ADYEN_CONNECTION_TIMEOUT=10

The convenience methods can optionally use separate product credentials:

ADYEN_LEGAL_ENTITY_MANAGEMENT_API_KEY=your-api-key
ADYEN_BALANCE_PLATFORM_API_KEY=your-api-key
ADYEN_CLOUD_DEVICE_API_KEY=your-api-key

Cloud Device uses Adyen's global test endpoint and defaults to its EU live endpoint.

Generated API clients

Resolve any generated service by its class. The returned service retains its concrete type for static analysis and IDE completion:

use Laraworld\Adyen\AdyenClient;
use Laraworld\Adyen\Generated\Checkout\PaymentsApi;

$adyen = app(AdyenClient::class);
$payments = $adyen->api(PaymentsApi::class);

Pass a configured credential name as the second argument when an API uses a separate key:

$payments = $adyen->api(PaymentsApi::class, 'checkout');

That resolves adyen.api_keys.checkout; named credentials fall back to ADYEN_API_KEY. You can add named keys to the published configuration as needed.

Convenience methods remain available for the APIs originally exposed by this wrapper:

$adyen = app(AdyenClient::class);

$businessLines = $adyen->businessLines();
$legalEntities = $adyen->legalEntities();
$onboarding = $adyen->hostedOnboarding();
$accountHolders = $adyen->balancePlatformAccountHolders();
$cloudDevice = $adyen->cloudDevice();

All 112 generated service classes also have concrete methods directly on AdyenClient:

$orders = $adyen->orders();
$transfers = $adyen->transfers();
$users = $adyen->usersCompanyLevel();

When generated class names collide, the API family is included in the method name:

$checkoutPayments = $adyen->checkoutPayments();
$paymentPayments = $adyen->paymentPayments();
$documentCollector = $adyen->documentCollectorDocuments();

Each method checks for an API-family credential such as adyen.api_keys.checkout before falling back to ADYEN_API_KEY.

Request and response objects live below Laraworld\Adyen\Generated in product-specific namespaces.

Generated methods expose query and header parameters as typed named arguments while retaining requestOptions for backward compatibility and cross-cutting options:

$result = $adyen->transfers()->getAllTransfers(
    createdSince: new DateTimeImmutable('-1 day'),
    createdUntil: new DateTimeImmutable(),
);

$result = $businessLines->getBusinessLine($businessLineId, requestOptions: [
    'headers' => ['X-Custom-Header' => 'value'],
    'idempotencyKey' => $idempotencyKey,
]);

Array query parameters follow their OpenAPI style and explode rules. Arbitrary headers and idempotency keys remain available through requestOptions.

Error handling

Transport and non-successful API responses throw ApiException:

use Laraworld\Adyen\Exceptions\ApiException;

try {
    $result = $adyen->checkoutPayments()->payments($request);
} catch (ApiException $exception) {
    report($exception);

    $status = $exception->statusCode();
    $response = $exception->responseBody();
}

Cloud Device and Terminal API

Terminal messages use the generated TerminalAPIRequest and TerminalAPIResponse roots:

use Laraworld\Adyen\Generated\TerminalApi\Model\MessageCategory;
use Laraworld\Adyen\Generated\TerminalApi\Model\MessageClass;
use Laraworld\Adyen\Generated\TerminalApi\Model\MessageHeader;
use Laraworld\Adyen\Generated\TerminalApi\Model\MessageType;
use Laraworld\Adyen\Generated\TerminalApi\Model\SaleToPOIRequest;
use Laraworld\Adyen\Generated\TerminalApi\Model\TerminalAPIRequest;

$request = new TerminalAPIRequest([
    'saleToPOIRequest' => new SaleToPOIRequest([
        'messageHeader' => new MessageHeader([
            'messageClass' => MessageClass::SERVICE,
            'messageCategory' => MessageCategory::PAYMENT,
            'messageType' => MessageType::REQUEST,
            'serviceID' => $serviceId,
            'saleID' => $saleId,
            'pOIID' => $deviceId,
        ]),
        'paymentRequest' => $paymentRequest,
    ]),
]);

$response = $cloudDevice->sendSyncDeviceMessageRequest(
    $merchantAccount,
    $deviceId,
    $request,
);

sendSyncDeviceMessageRequest() returns a TerminalAPIResponse. sendAsyncDeviceMessageRequest() returns the HTTP acknowledgement; the Terminal API result is delivered through a webhook.

Notification and webhook models

The 19 inbound specification families are provided as generated model classes only. This package does not route webhook payloads or verify webhook HMAC signatures. Verify incoming notifications according to Adyen's webhook security documentation before deserializing them into the corresponding Generated model namespace.

Regenerating the APIs

The specifications, source commit, checksums, namespaces, and generator image are pinned under resources/openapi. Refresh the manifest from Adyen and regenerate with:

composer update-openapi-sources
composer generate-apis
composer check-generated

update-openapi-sources selects only the highest numeric -vN.yaml file in each family. Generation also rebuilds the concrete AdyenClient accessor trait, so newly published service classes cannot drift from the public client surface. Review the generated diff before committing an upstream API update. Edit templates and generator scripts; do not edit anything under src/Generated directly.

Security and licensing

See SECURITY.md for vulnerability reporting. Webhook HMAC verification is not implemented by this package and must be performed before accepting incoming notifications.

This package is MIT licensed. Generated code and templates also incorporate third-party material; see THIRD_PARTY_NOTICES.md.

laraworld / adyen

Maintainers

Package info

Statistics

Security