Adyen PHP API Library

repository·main·Indexed 41 days ago

https://github.com/adyen/adyen-php-api-library

The official PHP client for interacting with Adyen's payment and financial APIs. It supports a wide range of services including Checkout API (v71), Payments API (v68), Recurring API (v68), Payouts API (v68), POS Mobile API (v68), Management API (v3), Disputes API (v30), BinLookup API (v54), Transfers API (v4), Account API (v5), and Fund API (v5). The library provides strongly typed model objects and associative array support for requests, as well as specialized parsers for Banking and Management webhooks.

Tokens: 11.8K
Snippets: 31
Records: 33
Agent score: 52%

What's inside Adyen

Adyen PHP API Library Overview
main
The Adyen PHP API Library is the officially supported PHP library for interacting with Adyen's APIs. It provides a structured way to integrate Adyen's payment services into PHP applications.
https://github.com/adyen/adyen-php-api-library/blob/main/README.md
Initialize the Adyen Client with Basic Auth
main
If your integration requires basic authentication instead of an API key, use setUsername() and setPassword() on the \Adyen\Client instance.
```
$client = new \Adyen\Client();
$client->setUsername("YOUR USERNAME");
$client->setPassword("YOUR PASSWORD");
$client->setEnvironment(\Adyen\Environment::TEST);
$client->setTimeout(30);
```
https://github.com/adyen/adyen-php-api-library/blob/main/README.md
Troubleshoot Payments webhook HMAC signatures
main
Use the HMACValidatorPayments.php script to verify or troubleshoot the HMAC signature calculation for Payments webhooks. You must provide the HMAC key used to generate the signature and the path to a JSON file containing the webhook payload.
Note: Ensure you are using the specific HMAC key associated with the payload in the JSON file.
```
php tools/hmac/HMACValidatorPayments.php {hmacKey} {path to JSON file}
```
https://github.com/adyen/adyen-php-api-library/blob/main/tools/hmac/README.md
Initialize the Adyen Client with an API Key
main
To make API calls, instantiate an >\Adyen\Client object. You should set up the client as a singleton resource. You must provide an API key using setXApiKey() and specify the environment using setEnvironment() (e.g., \Adyen\Environment::TEST or \Adyen\Environment::LIVE).
```
require __DIR__ . '/vendor/autoload.php';

$client = new \Adyen\Client();
$client->setXApiKey("YOUR API KEY");
$client->setEnvironment(\Adyen\Environment::TEST);
$client->setTimeout(30);
```
https://github.com/adyen/adyen-php-api-library/blob/main/README.md
Troubleshoot Banking webhook HMAC signatures
main
Use the HMACValidatorBanking.php script to verify or troubleshoot the HMAC signature calculation for Banking webhooks. You must provide the HMAC key used to generate the signature and the path to a JSON file containing the webhook payload.
Note: Ensure you are using the specific HMAC key associated with the payload in the JSON file.
```
php tools/hmac/HMACValidatorBanking.php {hmacKey} {path to JSON file}
```
https://github.com/adyen/adyen-php-api-library/blob/main/tools/hmac/README.md
Install the Adyen PHP API Library
main
Install the library using Composer. Ensure you have PHP 7.3 or later and the following extensions installed: ctype, curl, json, mbstring, and openssl.
If you are using PHP 7.2 or lower, you must use version 6.3.0 of the library.
```
composer require adyen/php-api-library
```
https://github.com/adyen/adyen-php-api-library/blob/main/README.md
Initialize the Adyen Client
main
The Adyen\Client class is the primary entry point for interacting with Adyen's API services. You can initialize it by passing an optional Adyen\Config object. If no config is provided, a default configuration is used.
```
use Adyen\Client;
use Adyen\Config;

// Using default configuration
$client = new Client();

// Using a custom configuration
$config = new Config();
$client = new Client($config);
```
```
use Adyen\Client;
use Adyen\Config;

$client = new Client();
```
https://github.com/adyen/adyen-php-api-library/blob/main/src/Adyen/Client.php
Configure the Adyen Client environment
main
Use setEnvironment() to switch between Adyen's test and live platforms.
- Test Environment: Uses Environment::TEST and points to test endpoints.
- Live Environment: Uses Environment::LIVE. For live environments, you should provide a liveEndpointUrlPrefix obtained from your Adyen Customer Area to ensure requests are routed to your unique live URL.
If you are in a live environment and do not provide a prefix, the client defaults to the standard live endpoint, but endpointCheckout will be set to null as it requires a unique identifier.
```
// Set to test environment
$client->setEnvironment(Adyen\Environment::TEST);

// Set to live environment with a specific prefix
$client->setEnvironment(Adyen\Environment::LIVE, 'your-unique-prefix');
```
```
$client->setEnvironment(Adyen\Environment::TEST);
$client->setEnvironment(Adyen\Environment::LIVE, 'your-unique-prefix');
```
https://github.com/adyen/adyen-php-api-library/blob/main/src/Adyen/Client.php

Parse Banking and Management Webhooks

main

To handle incoming webhooks, first validate the HMAC signature. Once validated, use the specific parser service to extract the webhook data.

For Banking Webhooks, use \Adyen\Service\BankingWebhookParser. For Management Webhooks, use \Adyen\Service\ManagementWebhookParser.

// Example for Banking Webhooks
$jsonString = 'webhook_payload';
$isValid = $hmac->validateHMAC("YOUR_HMAC_KEY", "YOUR_HMAC_SIGN", $jsonString);

if ($isValid) {
    $webhookParser = new \Adyen\Service\BankingWebhookParser($jsonString);
    $result = $webhookParser->getGenericWebhook();
}

// Example for Management Webhooks
$jsonString = 'webhook_payload';
$isValid = $hmac->validateHMAC("YOUR_HMAC_KEY", "YOUR_HMAC_SIGN", $jsonString);

if ($isValid) {
    $webhookParser = new \Adyen\Service\ManagementWebhookParser($jsonString);
    $result = $webhookParser->getGenericWebhook();
}

Make a Payment Request using strongly typed objects

main

The preferred way to interact with the API is by instantiating strongly typed model objects for requests. For example, to process a payment, you create PaymentMethod, Amount, and PaymentRequest objects, then pass the request object to the appropriate service (e.g., \Adyen\Service\Checkout\PaymentsApi).

$client = new \Adyen\Client();
$client->setXApiKey("YOUR API KEY");
$client->setEnvironment(\Adyen\Environment::TEST);
$client->setTimeout(30);

$service = new \Adyen\Service\Checkout\PaymentsApi($client);

// Create PaymentMethod object
$paymentMethod = new \Adyen\Model\Checkout\CheckoutPaymentMethod();
$paymentMethod
    ->setType("scheme")
    ->setEncryptedBankAccountNumber("test_4111111111111111")
    ->setEncryptedExpiryMonth("test_03")
    ->setEncryptedExpiryYear("test_2030")
    ->setEncryptedSecurityCode("test_737");

// Creating Amount Object
$amount = new \Adyen\Model\Checkout\Amount();
$amount
    ->setValue(1500)
    ->setCurrency("EUR");

// Create the actual Payments Request
$paymentRequest = new \Adyen\Model\Checkout\PaymentRequest();
$paymentRequest
    ->setMerchantAccount("YOUR MERCHANT ACCOUNT")
    ->setPaymentMethod($paymentMethod)
    ->setAmount($amount)
    ->setReference("payment-test")
    ->setReturnUrl("https://your-company.com/...");

$result = $service->payments($paymentRequest);

Make a Payment Request using associative arrays

main

For easier migration from older implementations, you can instantiate request objects using associative arrays via the arrayAccess implementation. This allows you to pass a raw array to the constructor of a model class.

$service = new \Adyen\Service\Checkout\PaymentLinksApi($client);

$params = array(
    'merchantAccount' => "YourMerchantAccount",
    'reference' => '12345',
    'amount' => array('currency' => "BRL", 'value' => 1250),
    'countryCode' => "BR",
    'shopperReference' => "YourUniqueShopperId",
    'shopperEmail' => "test@email.com",
    'shopperLocale' => "pt_BR",
    'billingAddress' => array(...),
    'deliveryAddress' => array(...),
);

$createPaymentLinkRequest = new \Adyen\Model\Checkout\PaymentLinkRequest($params);

$result = $service->paymentLinks($createPaymentLinkRequest);

$paymentLink = $result->getUrl(); // or use $result['url'] if you want to use arrayAccess

Supported API versions and services

main

The Adyen PHP API Library supports a wide range of services, each mapped to a specific service class within the library. When integrating, ensure you are using the service class that corresponds to the API version required by your business logic.

Key services include:

Checkout API (v71): For initiating and authorizing online payments (cards, wallets, local methods).
Payments API (v68): For initiating, settling, and modifying payments.
Recurring API (v68): For managing tokens or saved payment details.
Payouts API (v68): For storing, confirming, or declining payouts.
POS Mobile API (v68): For mutual authentication between POS Mobile SDKs and the Adyen platform.
Management API (v3): For configuring merchant accounts, stores, and terminals.
Disputes API (v30): For automating dispute handling and chargebacks.
BinLookup API (v54): For retrieving information based on a BIN.
Transfers API (v4): For transaction information and moving funds.
Account API (v5): For managing account holders, bank accounts, and verification documents.
Fund API (v5): For managing funds and account balances.

Refer to the specific service class in src/Adyen/Service/ to interact with these APIs.

| API | Description | Service Name | Supported version |
|------------------------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-------------------------------------------------------------------------|--------------------------|
| [BIN Lookup API](https://docs.adyen.com/api-explorer/BinLookup/54/overview) | The BIN Lookup API provides endpoints for retrieving information based on a given BIN. | [Binlookup](src/Adyen/Service/BinLookupApi.php) | **v54** |
| [Checkout API](https://docs.adyen.com/api-explorer/Checkout/71/overview) | Adyen Checkout API provides a simple and flexible way to initiate and authorise online payments. | [Checkout](src/Adyen/Service/Checkout) | **v71** |
| [Configuration API](https://docs.adyen.com/api-explorer/balanceplatform/2/overview) | The Configuration API enables you to create a platform where you can onboard your users. | [BalancePlatform](src/Adyen/Service/BalancePlatform/) | **v2** |
| [DataProtection API](https://docs.adyen.com/development-resources/data-protection-api) | Process Subject Erasure Requests as mandated in GDPR. | [DataProtection](src/Adyen/Service/DataProtectionApi.php) | **v1** |
| [Management API](https://docs.adyen.com/api-explorer/Management/3/overview) | Configure and manage your Adyen company and merchant accounts. | [Management](src/Adyen/Service/Management/) | **v3** |
| [Payments API](https://docs.adyen.com/api-explorer/Payment/68/overview) | Initiate, settle, and modify payments. | [Payments](src/Adyen/Service/Payments) | **v68** |
| [Recurring API](https://docs.adyen.com/api-explorer/Recurring/68/overview) | Manage and remove tokens or saved payment details. | [Recurring](src/Adyen/Service/RecurringApi.php) | **v68** |
| [Payouts API](https://docs.adyen.com/api-explorer/Payout/68/overview) | Store payout details, confirm, or decline a payout. | [Payout](src/Adyen/Service/Payout) | **v68** |
| [Stored Value API](https://docs.adyen.com/payment-methods/gift-cards/stored-value-api) | Manage online and point-of-sale gift cards. | [StoredValue](src/Adyen/Service/StoredValueApi.php) | **v46** |
| [Legal Entity Management API](https://docs.adyen.com/api-explorer/legalentity/3/overview) | Manage legal entities for verification. | [LegalEntityManagement](src/Adyen/Service/LegalEntityManagement) | **v3** |
| [Transfers API](https://docs.adyen.com/api-explorer/transfers/4/overview) | Get transaction info and move funds. | [Transfers](src/Adyen/Service/Transfers) | **v4** |
| [Balance Control API](https://docs.adyen.com/api-explorer/BalanceControl/1/overview) | Transfer funds between merchant accounts. | [BalanceControl](src/Adyen/Service/BalanceControlApi.php) | **v1** |
| [Hosted Onboarding API](https://docs.adyen.com/api-explorer/Hop/1/overview) | Generate links to Adyen-hosted onboarding pages. | [HostedOnboardingPages](src/Adyen/Service/Hop.php) | **v1** |
| [Account API](https://docs.adyen.com/api-explorer/Account/5/overview) | Manage account holders, accounts, and bank accounts. | [Account](src/Adyen/Service/Account.php) | **v5** |
| [Fund API](https://docs.adyen.com/api-explorer/Fund/5/overview) | Manage funds and retrieve balances. | [Fund](src/Adyen/Service/Fund.php) | **v5** |
| [Disputes API](https://docs.adyen.com/api-explorer/Disputes/30/overview) | Automate dispute handling and chargebacks. | [Disputes](src/Adyen/Service/DisputesApi.php) | **v30** |
| [POS Mobile API](https://docs.adyen.com/api-explorer/possdk/68/overview) | Mutual authentication for POS Mobile SDKs. | [POS Mobile](src/Adyen/Service/PosMobile.php) | **v68** |
| [Payments App API](https://docs.adyen.com/api-explorer/payments-app/1/overview) | Board and manage the Adyen Payments App. | [PaymentsAppApi](src/Adyen/Service/PaymentsApp/PaymentsAppApi.php) | **v1** |