- A convenient PHP wrapper around API calls and responses:
- marshals PHP request objects to HTTP requests
- unmarshals HTTP responses to PHP response objects or PHP exceptions
- handling of all the details concerning authentication
- handling of required metadata
For a general introduction to the API and various checkout flows, see the documentation: - General introduction to the PAYONE Commerce Platform - Overview of the checkout flows - Available payment methods
This SDK requires PHP 8.2 or later.
This SDK is currently not released on packagist. You can install it from GitHub by specifying a vcs repository within your composer.json:
{
"repositories": [
{
"type": "vcs",
"url": "https://github.com/PAYONE-GmbH/PCP-ServerSDK-php"
}
],
"require": {
"payone-gmbh/pcp-serversdk-php": "dev-main"
}
}These snippets specify the main branch, which contains the latest release. You can specify a version by inserting a git tag vX.Y.Z instead of main. Make sure to prepend the git branch or tag with dev-. For an in depth explanation take a look at the Composer documentation.
To use this SDK, you need to construct a CommunicatorConfiguration which encapsulates everything needed to connect to the PAYONE Commerce Platform.
<?php
use PayoneCommercePlatform\Sdk\CommunicatorConfiguration;
/** @var CommunicatorConfiguration */
$config = new CommunicatorConfiguration(
apiKey: getenv('API_KEY'),
apiSecret: getenv('API_SECRET'),
host: CommunicatorConfiguration::getPredefinedHosts()['prod']['url'],
integrator: 'YOUR COMPANY NAME',
);As shown above, you can use CommunicatorConfiguration::getPredefinedHosts() for information on the available environments. With the configuration you can create an API client for each reource you want to interact with. For example to create a commerce case you can use the CommerceCaseApiClient.
<?php
use PayoneCommercePlatform\Sdk\ApiClient\CommerceCaseApiClient;
$client = new CommerceCaseApiClient($config);Each client has typed parameters for the payloads and responses. You can use phpstan to verify the types of the parameters and return values or look for TypeError thrown at runtime. All payloads are availble as PHP classes within the PayoneCommercePlatform\Sdk\Models namespace. The SDK will automatically marshal the PHP objects to JSON and send it to the API. The response will be unmarshalled to a PHP object internally.
To create an empty commerce case you can use the CreateCommerceCaseRequest class:
<?php
use PayoneCommercePlatform\Sdk\Models\CreateCommerceCaseResponse;
use PayoneCommercePlatform\Sdk\Models\CreateCommerceCaseRequest;
/** @var CreateCommerceCaseResponse */
$response = $client->createCommerceCase('YOUR_MERCHANT_ID', new CreateCommerceCaseRequest());The models are directly map to the API as described in the PAYONE Commerce Platform API Reference. For an in depth example you can take a look at the demo app.
When making a request, any client instance may throw a PayoneCommercePlatform\Sdk\Errors\ApiException. There are two subtypes of this exception:
PayoneCommercePlatform\Sdk\Errors\ApiErrorResponseException: This exception is thrown when the API returns an well-formed error response. These errors are provided as an array ofPayoneCommercePlatform\Sdk\Models\APIErrorinstances via thegetErrors()method on the exception. They usually contain useful information about what is wrong in your request or the state of the resource.PayoneCommercePlatform\Sdk\Errors\ApiResponseRetrievalException: This exception is a catch-all exception for any error that cannot be turned into a helpful error response. This includes network errors, malformed responses or other errors that are not directly related to the API.
For most payment methods, some information from the client is needed, e.g. payment information given by Apple when a payment via ApplePay suceeds. PAYONE provides client side SDKs which helps you interact the third party payment providers. You can find these SDKs under the Payone GitHub organization. Either way ensure to never store or even send credit card information to your server. The PAYONE Commerce Platform never needs access to the credit card information. The client side is responsible for safely retrieving a credit card token. This token must be used with this SDK.
This SDK makes no assumptions about how networking between the client and your PHP server is handled. If need to serialize a model to JSON or deserialize a client side request from a JSON string to a model you can use the static serializeJson() and deserializeJson() methods on the BaseApiClient class:
<?php
use PayoneCommercePlatform\Sdk\ApiClient\BaseApiClient;
use PayoneCommercePlatform\Sdk\Models\ApplePay\AppelPayPayment;
// to json
// make sure to add some useful data
$applePayPayment = new ApplePayPayment();
$json = BaseApiClient::serializeJson($model);
// ...and back
$applePayPaymentRequest = BaseApiClient::deserializeJson($json, ApplePayPayment::class);As every API clients inherits from BaseApiClient you can use these methods on every client class directly.
<?php
use PayoneCommercePlatform\Sdk\ApiClient\PaymentInformationApiClient;
use PayoneCommercePlatform\Sdk\Models\AmountOfMoney;
$amountOfMoney = new AmountOfMoney(amount: 3199, currencyCode: 'EUR');
PaymentInformationApiClient::serializeJson($amountOfMoney);
// returns:
// '{ "amount": 3199, currencyCode: "EUR" }'When a client successfully makes a payment via ApplePay, it receives a ApplePayPayment. This structure is accessible as a model as PayoneCommercePlatform\Sdk\Models\ApplePay\ApplePayPayment. The model is a direct representation of the ApplePayPayment. You can use the deserializeJson() method to convert a JSON string from a client an ApplePayPayment object.
<?php
use PayoneCommercePlatform\Sdk\ApiClient\BaseApiClient;
// receive json as a string from the client with your favorite networking library or server framework
/** @var string */
$json = getJsonStringFromRequestSomehow();
$applePayPayment = BaseApiClient::deserializeJson($json, ApplePayPayment::class);You can use the PayoneCommercePlatform\Sdk\Transformer\ApplePayTransformer to map an ApplePayPayment to a MobilePaymentMethodSpecificInput which can be used for payment executions or order requests. The transformer has a static method transformApplePayPaymentToMobilePaymentMethodSpecificInput() which takes an ApplePayPayment and returns a MobilePaymentMethodSpecificInput. The transformer does not check if the reponse is complete. If anything is missing the field will be set to null.
<?php
use PayoneCommercePlatform\Sdk\Transformer\ApplePayTransformer;
$mobilePaymentMethodSpecificInput = ApplePayTransformer::transformApplePayPaymentToMobilePaymentMethodSpecificInput($applePayPayment);This repository contains a demo app that showcases how to implement common use cases, like a Step-by-Step Checkout and an One-Stop-Checkout. For each use case the demo app contains a protected method in the top level class DemoApp. You can run the app to execute the code within in the sandbox API. This is a good way to test, if your setup is correct.
Before running the app ensure you have run composer install and composer dumb-autoload within the demo app directory (./examples/demo-app). By default, all API calls are sent to the pre-production environment of the PAYONE Commerce Platform. Note that the created entities cannot be completely deleted.
You can run it within the demo app directory via php src/DemoApp.php, make sure to provide all necessary environment variables:
API_KEYa valid api key for the PAYONE Commerce PlatformAPI_SECRETa valid api secret for the PAYONE Commerce PlatformMERCHANT_IDthe merchant id which is needed to identify entities, e.g. commerce cases and checkouts, that belong to you.
All contents of this SDK are availble under the namespace PayoneCommercePlatform\Sdk. The SDK groups the endpoints of every resource into its own client, e.g. the PayoneCommercePlatform\Sdk\ApiClient\CheckoutApiClient can be used to interact with a checkout. To instantiate a singular client a PayoneCommercePlatform\Sdk\CommunicatorConfiguration instance has to provided which at least needs an API Key and Secret to connect to PAYONE Commerce Platform. The reponses and requests as well as their contained objects are provided as PHP classes and enums within the PayoneCommercePlatform\Sdk\Models namespace.
The CommunicatorConfiguration class is responsible for configuring the connection to the PAYONE Commerce Platform. This class holds essential information such as API keys, host URLs, and metadata required to authenticate and interact with the platform's API. Its needed as configuration to interact with any of the resources. Ensure that the API key and secret are securely stored and only passed to the configuration instance when needed.
To create a configuration object apiKey and apiSecret are required. You can use CommunicatorConfiguration::getPredefinedHosts() to get information about different environments of the PAYONE Commerce Platform. Currently prod and preprod are available. You should also provide an integrator as a string, this helps us in debugging and monitoring process.
<?php
use PayoneCommercePlatform\Sdk\CommunicatorConfiguration;
/** @var CommunicatorConfiguration */
$config = new CommunicatorConfiguration(
apiKey: getenv('API_KEY'),
apiSecret: getenv('API_SECRET'),
host: CommunicatorConfiguration::getPredefinedHosts()['prod']['url'],
integrator: 'YOUR COMPANY NAME',
);You shouldn't need to provide serverMetaInfo. This property can automatically be detected. and will send your OS, PHP Version and SDK to the PCP for debugging purposes.
SDK_VERSION
Description: The version of the SDK.
type: string
public function __construct(
string $apiKey,
string $apiSecret,
?string $host = null,
?string $integrator = null,
?array $serverMetaInfo = null,
?array $clientMetaInfo = null
)Description:
Constructor to initialize the configuration with required and optional parameters.
Parameters:
string $apiKey: The API key for authentication.string $apiSecret: The API secret for authentication.string|null $host: The host URL for the PAYONE Commerce Platform API. Defaults to the production URL if not provided.string|null $integrator: Information about the integrator using the SDK.array|null $serverMetaInfo: Metadata about the server environment.array|null $clientMetaInfo: Metadata about the client environment.
public function setApiKey(string $apiKey): selfDescription:
Sets the API key.
Parameters:
string $apiKey: The API key for authentication.
Returns:
self
public function getApiKey(): stringDescription:
Gets the API key.
Returns:
string - The API key.
public function setApiSecret(string $apiSecret): selfDescription:
Sets the API secret.
Parameters:
string $apiSecret: The API secret for authentication.
Returns:
self
public function getApiSecret(): stringDescription:
Gets the API secret.
Returns:
string - The API secret.
public function getIntegrator(): ?stringDescription:
Gets the integrator information.
Returns:
string|null - The integrator information, or null if not set.
public function setIntegrator(?string $integrator): selfDescription:
Sets the integrator information.
Parameters:
string|null $integrator: The integrator information.
Returns:
self
public function setHost(string $host): selfDescription:
Sets the host URL. Automatically removes any trailing slash from the provided URL.
Parameters:
string $host: The host URL for the PAYONE Commerce Platform API.
Returns:
self
public function getHost(): stringDescription:
Gets the host URL.
Returns:
string - The host URL.
public function getClientMetaInfo(): arrayDescription:
Gets the client metadata information.
Returns:
array<string, string> - The client metadata information.
public function setClientMetaInfo(array $clientMetaInfo): selfDescription:
Sets the client metadata information.
Parameters:
array<string, string> $clientMetaInfo: The client metadata information.
Returns:
self
public function addClientMetaInfo(string $key, string $value): selfDescription:
Adds an entry to the client metadata information.
Parameters:
string $key: The key for the metadata entry.string $value: The value for the metadata entry.
Returns:
self
public function getServerMetaInfo(): arrayDescription:
Gets the server metadata information.
Returns:
array<string, string> - The server metadata information.
public function setServerMetaInfo(array $serverMetaInfo): selfDescription:
Sets the server metadata information.
Parameters:
array<string, string> $serverMetaInfo: The server metadata information.
Returns:
self
public function addServerMetaInfo(string $key, string $value): selfDescription:
Adds an entry to the server metadata information.
Parameters:
string $key: The key for the metadata entry.string $value: The value for the metadata entry.
Returns:
self
public static function getPredefinedHosts(): arrayDescription:
Gets an array of predefined host settings for the PAYONE Commerce Platform.
Returns:
array<string, array{url: string, description: string}> - An array of predefined host settings.
For the getCommerceCases() and getCheckouts() you set the query parameter by passing a PayoneCommercePlatform\Sdk\Models\GetCommerceCasesQuery or PayoneCommercePlatform\Sdk\Models\GetCheckoutsQuery respectively. These objects have typed properties which can be set to filter the results. The conversion from the object to a query string is done automatically by the SDK.
The properties are directly mapped to the query parameters of the commerce case API
The GetCommerceCasesQuery class is used to build and structure query parameters when fetching commerce cases via the PAYONE Commerce Platform API. It allows you to filter and limit the results by various criteria such as date range, merchant details, checkout status, and payment channels.
- Type:
int|null - Description: The offset of the first item in the result set. This is used for pagination.
- Setter:
public function setOffset(?int $offset): self - Getter:
public function getOffset(): ?int
- Type:
int|null - Description: The maximum number of items to return in the result set. This is used for pagination.
- Setter:
public function setSize(?int $size): self - Getter:
public function getSize(): ?int
- Type:
DateTime|null - Description: The start date for filtering commerce cases.
- Setter:
public function setFromDate(?DateTime $fromDate): self - Getter:
public function getFromDate(): ?DateTime
- Type:
DateTime|null - Description: The end date for filtering commerce cases.
- Setter:
public function setToDate(?DateTime $toDate): self - Getter:
public function getToDate(): ?DateTime
- Type:
string|null - Description: The unique identifier for a commerce case.
- Setter:
public function setCommerceCaseId(?string $commerceCaseId): self - Getter:
public function getCommerceCaseId(): ?string
- Type:
string|null - Description: A reference identifier provided by the merchant.
- Setter:
public function setMerchantReference(?string $merchantReference): self - Getter:
public function getMerchantReference(): ?string
- Type:
string|null - Description: The unique identifier of the customer as provided by the merchant.
- Setter:
public function setMerchantCustomerId(?string $merchantCustomerId): self - Getter:
public function getMerchantCustomerId(): ?string
- Type:
array<StatusCheckout>|null - Description: An array of
StatusCheckoutenums to filter commerce cases by checkout status. - Setter:
public function setIncludeCheckoutStatus(?array $includeCheckoutStatus): self - Getter:
public function getIncludeCheckoutStatus(): ?array
- Type:
array<PaymentChannel>|null - Description: An array of
PaymentChannelenums to filter commerce cases by payment channels. - Setter:
public function setIncludePaymentChannel(?array $includePaymentChannel): self - Getter:
public function getIncludePaymentChannel(): ?array
The properties are directly mapped to the query parameters of the checkout API
The GetCheckoutsQuery class is used to build and structure query parameters when fetching checkout data via the PAYONE Commerce Platform API. It allows you to filter and limit the results by various criteria such as date range, amounts, merchant details, checkout statuses, and payment channels.
- Type:
int|null - Description: The offset of the first item in the result set. This is used for pagination.
- Setter:
public function setOffset(?int $offset): self - Getter:
public function getOffset(): ?int
- Type:
int|null - Description: The maximum number of items to return in the result set. This is used for pagination.
- Setter:
public function setSize(?int $size): self - Getter:
public function getSize(): ?int
- Type:
DateTime|null - Description: The start date for filtering checkouts.
- Setter:
public function setFromDate(?DateTime $fromDate): self - Getter:
public function getFromDate(): ?DateTime
- Type:
DateTime|null - Description: The end date for filtering checkouts.
- Setter:
public function setToDate(?DateTime $toDate): self - Getter:
public function getToDate(): ?DateTime
- Type:
int|null - Description: The minimum checkout amount for filtering.
- Setter:
public function setFromCheckoutAmount(?int $fromCheckoutAmount): self - Getter:
public function getFromCheckoutAmount(): ?int
- Type:
int|null - Description: The maximum checkout amount for filtering.
- Setter:
public function setToCheckoutAmount(?int $toCheckoutAmount): self - Getter:
public function getToCheckoutAmount(): ?int
- Type:
int|null - Description: The minimum open amount for filtering.
- Setter:
public function setFromOpenAmount(?int $fromOpenAmount): self - Getter:
public function getFromOpenAmount(): ?int
- Type:
int|null - Description: The maximum open amount for filtering.
- Setter:
public function setToOpenAmount(?int $toOpenAmount): self - Getter:
public function getToOpenAmount(): ?int
- Type:
int|null - Description: The minimum collected amount for filtering.
- Setter:
public function setFromCollectedAmount(?int $fromCollectedAmount): self - Getter:
public function getFromCollectedAmount(): ?int
- Type:
int|null - Description: The maximum collected amount for filtering.
- Setter:
public function setToCollectedAmount(?int $toCollectedAmount): self - Getter:
public function getToCollectedAmount(): ?int
- Type:
int|null - Description: The minimum cancelled amount for filtering.
- Setter:
public function setFromCancelledAmount(?int $fromCancelledAmount): self - Getter:
public function getFromCancelledAmount(): ?int
- Type:
int|null - Description: The maximum cancelled amount for filtering.
- Setter:
public function setToCancelledAmount(?int $toCancelledAmount): self - Getter:
public function getToCancelledAmount(): ?int
- Type:
int|null - Description: The minimum refund amount for filtering.
- Setter:
public function setFromRefundAmount(?int $fromRefundAmount): self - Getter:
public function getFromRefundAmount(): ?int
- Type:
int|null - Description: The maximum refund amount for filtering.
- Setter:
public function setToRefundAmount(?int $toRefundAmount): self - Getter:
public function getToRefundAmount(): ?int
- Type:
int|null - Description: The minimum chargeback amount for filtering.
- Setter:
public function setFromChargebackAmount(?int $fromChargebackAmount): self - Getter:
public function getFromChargebackAmount(): ?int
- Type:
int|null - Description: The maximum chargeback amount for filtering.
- Setter:
public function setToChargebackAmount(?int $toChargebackAmount): self - Getter:
public function getToChargebackAmount(): ?int
- Type:
string|null - Description: The unique identifier of the checkout.
- Setter:
public function setCheckoutId(?string $checkoutId): self - Getter:
public function getCheckoutId(): ?string
- Type:
string|null - Description: A reference identifier provided by the merchant.
- Setter:
public function setMerchantReference(?string $merchantReference): self - Getter:
public function getMerchantReference(): ?string
- Type:
string|null - Description: The unique identifier of the customer as provided by the merchant.
- Setter:
public function setMerchantCustomerId(?string $merchantCustomerId): self - Getter:
public function getMerchantCustomerId(): ?string
- Type:
array<string>|null - Description: An array of payment product IDs to include in the search.
- Setter:
public function setIncludePaymentProductId(?array $includePaymentProductId): self - Getter:
public function getIncludePaymentProductId(): ?array
- Type:
array<StatusCheckout>|null - Description: An array of
StatusCheckoutenums to filter checkouts by status. - Setter:
public function setIncludeCheckoutStatus(?array $includeCheckoutStatus): self - Getter:
public function getIncludeCheckoutStatus(): ?array
- Type:
array<ExtendedCheckoutStatus>|null - Description: An array of
ExtendedCheckoutStatusenums to filter checkouts by extended status. - Setter:
public function setIncludeExtendedCheckoutStatus(?array $includeExtendedCheckoutStatus): self - Getter:
public function getIncludeExtendedCheckoutStatus(): ?array
- Type:
array<PaymentChannel>|null - Description: An array of
PaymentChannelenums to filter checkouts by payment channel. - Setter:
public function setIncludePaymentChannel(?array $includePaymentChannel): self - Getter:
public function getIncludePaymentChannel(): ?array
- Type:
string|null - Description: The payment reference for filtering.
- Setter:
public function setPaymentReference(?string $paymentReference): self - Getter:
public function getPaymentReference(): ?string
- Type:
string|null - Description: The payment ID for filtering.
- Setter:
public function setPaymentId(?string $paymentId): self - Getter:
public function getPaymentId(): ?string
- Type:
string|null - Description: The first name of the customer for filtering.
- Setter:
public function setFirstName(?string $firstName): self - Getter:
public function getFirstName(): ?string
- Type:
string|null - Description: The surname of the customer for filtering.
- Setter:
public function setSurname(?string $surname): self - Getter:
public function getSurname(): ?string
- Type:
string|null - Description: The email of the customer for filtering.
- Setter:
public function setEmail(?string $email): self - Getter:
public function getEmail(): ?string
- Type:
string|null - Description: The phone number of the customer for filtering.
- Setter:
public function setPhoneNumber(?string $phoneNumber): self - Getter:
public function getPhoneNumber(): ?string
- Type:
string|null - Description: The date of birth of the customer for filtering.
- Setter:
public function setDateOfBirth(?string $dateOfBirth): self - Getter:
public function getDateOfBirth(): ?string
- Type:
string|null - Description: The company information for filtering.
- Setter:
public function setCompanyInformation(?string $companyInformation): self - Getter:
public function getCompanyInformation(): ?string
There's a API client class for each resource:
PayoneCommercePlatform\Sdk\ApiClient\CheckoutApiClientPayoneCommercePlatform\Sdk\ApiClient\CommerceCaseApiClientPayoneCommercePlatform\Sdk\ApiClient\OrderManagementCheckoutActionsApiClientPayoneCommercePlatform\Sdk\ApiClient\PaymentExecutionApiClientPayoneCommercePlatform\Sdk\ApiClient\PaymentInformationApiClient
All clients inherit from PayoneCommercePlatform\Sdk\ApiClient\BaseApiClient. You may want to use its static methods to serialize and deserialize JSON strings to models from this SDK. The respective methods serializeJson() and deserializeJson() are available on every client class as static methods as well. Note that these methods have undefined behavior when used with classes that are not part of this SDK.
Description:
A generic function that deserializes a JSON string into an instance of the specified class type.
Parameters:
string $data: The JSON string to deserialize.class-string<T>: The fully qualified class name of the type to deserialize the JSON string into.
Returns:
T- An instance of the specified class type
Exceptions:
NotEncodableValueExceptionUnexpectedValueException
Description:
Serializes an object or array into a JSON string. The method ensures that empty objects are serialized as '{}' rather than '[]'. Any property that itself maybe a model from the PayoneCommercePlatform\Sdk\Models namespace or an array of models is resursively serialized. T
Parameters:
mixed $data: The data to be serialized into a JSON string.
Returns:
string: A JSON string representing the input data.
The CheckoutApiClient class provides methods to interact with the Checkout resource of the PAYONE Commerce Platform API. This includes creating, updating, retrieving, and deleting checkouts within a commerce case.
You can create a CheckoutApiClient by providing a CommunicatorConfiguration. All endpoints are directly exposed as methods on the instance.
<?php
use PayoneCommercePlatform\Sdk\ApiClient\CheckoutApiClient;
$config = new CommunicatorConfiguration('API_KEY', 'API_SECRET');
$client = new CheckoutApiClient($config);public function createCheckout(
string $merchantId,
string $commerceCaseId,
CreateCheckoutRequest $createCheckoutRequest
): CreateCheckoutResponseDescription:
Creates a new checkout within an existing commerce case.
Parameters:
string $merchantId: The unique identifier of the merchant. A Checkout is associated with exactly one merchant.string $commerceCaseId: The unique identifier of a commerce case.CreateCheckoutRequest $createCheckoutRequest: The request body containing details for creating the checkout.
Returns:
CreateCheckoutResponse - The response object containing details of the created checkout.
Exceptions:
ApiErrorResponseExceptionApiResponseRetrievalException
public function deleteCheckout(
string $merchantId,
string $commerceCaseId,
string $checkoutId
): voidDescription:
Deletes an existing checkout.
Parameters:
string $merchantId: The unique identifier of the merchant.string $commerceCaseId: The unique identifier of a commerce case.string $checkoutId: The unique identifier of the checkout to be deleted.
Returns:
void
Exceptions:
ApiErrorResponseExceptionApiResponseRetrievalException
public function getCheckout(
string $merchantId,
string $commerceCaseId,
string $checkoutId
): CheckoutResponseDescription:
Retrieves details of a specific checkout.
Parameters:
string $merchantId: The unique identifier of the merchant.string $commerceCaseId: The unique identifier of a commerce case.string $checkoutId: The unique identifier of the checkout to retrieve.
Returns:
CheckoutResponse - The response object containing details of the retrieved checkout.
Exceptions:
ApiErrorResponseExceptionApiResponseRetrievalException
public function getCheckouts(
string $merchantId,
GetCheckoutsQuery $query = new GetCheckoutsQuery()
): CheckoutsResponseDescription:
Retrieves a list of checkouts based on the provided search parameters.
Parameters:
string $merchantId: The unique identifier of the merchant.GetCheckoutsQuery $query: The query parameters used to filter the checkouts.
Returns:
CheckoutsResponse - The response object containing a list of checkouts that match the search parameters.
Exceptions:
ApiErrorResponseExceptionApiResponseRetrievalException
public function updateCheckout(
string $merchantId,
string $commerceCaseId,
string $checkoutId,
PatchCheckoutRequest $patchCheckoutRequest
): voidDescription:
Modifies an existing checkout.
Parameters:
string $merchantId: The unique identifier of the merchant.string $commerceCaseId: The unique identifier of a commerce case.string $checkoutId: The unique identifier of the checkout to be updated.PatchCheckoutRequest $patchCheckoutRequest: The request body containing the modifications to be applied to the checkout.
Returns:
void
Exceptions:
ApiErrorResponseExceptionApiResponseRetrievalException
The CommerceCaseApiClient class provides methods to interact with the Commerce Case resource of the PAYONE Commerce Platform API. This includes creating, updating, retrieving, and searching commerce cases.
You can create a CommerceCaseApiClient by providing a CommunicatorConfiguration. All endpoints are directly exposed as methods on the instance.
<?php
use PayoneCommercePlatform\Sdk\ApiClient\CommerceCaseApiClient;
$config = new CommunicatorConfiguration('API_KEY', 'API_SECRET');
$client = new CommerceCaseApiClient($config);public function createCommerceCase(
string $merchantId,
CreateCommerceCaseRequest $createCommerceCaseRequest
): CreateCommerceCaseResponseDescription:
Creates a new commerce case for a specified merchant.
Parameters:
string $merchantId: The unique identifier of the merchant. A Commerce Case is associated with exactly one merchant.CreateCommerceCaseRequest $createCommerceCaseRequest: The request body containing details for creating the commerce case.
Returns:
CreateCommerceCaseResponse - The response object containing details of the created commerce case.
Exceptions:
ApiErrorResponseExceptionApiResponseRetrievalException
public function getCommerceCase(
string $merchantId,
string $commerceCaseId
): CommerceCaseResponseDescription:
Retrieves details of a specific commerce case.
Parameters:
string $merchantId: The unique identifier of the merchant.string $commerceCaseId: The unique identifier of the commerce case to retrieve.
Returns:
CommerceCaseResponse - The response object containing details of the retrieved commerce case.
Exceptions:
ApiErrorResponseExceptionApiResponseRetrievalException
public function getCommerceCases(
string $merchantId,
GetCommerceCasesQuery $query = new GetCommerceCasesQuery()
): arrayDescription:
Retrieves a list of commerce cases based on the provided search parameters.
Parameters:
string $merchantId: The unique identifier of the merchant.GetCommerceCasesQuery $query: The query parameters used to filter the commerce cases.
Returns:
array<CommerceCaseResponse> - An array of CommerceCaseResponse objects representing the retrieved commerce cases.
Exceptions:
ApiErrorResponseExceptionApiResponseRetrievalException
public function updateCommerceCase(
string $merchantId,
string $commerceCaseId,
Customer $customer
): voidDescription:
Updates an existing commerce case with new customer information.
Parameters:
string $merchantId: The unique identifier of the merchant.string $commerceCaseId: The unique identifier of the commerce case to update.Customer $customer: The customer data to update in the commerce case.
Returns:
void
Exceptions:
ApiErrorResponseExceptionApiResponseRetrievalException
The OrderManagementCheckoutActionsApiClient class provides methods to manage orders related to checkouts within a commerce case. This includes operations such as creating, canceling, delivering, and returning orders.
You can create a OrderManagementCheckoutActionsApiClient by providing a CommunicatorConfiguration. All endpoints are directly exposed as methods on the instance.
<?php
use PayoneCommercePlatform\Sdk\ApiClient\OrderManagementCheckoutActionsApiClient;
$config = new CommunicatorConfiguration('API_KEY', 'API_SECRET');
$client = new OrderManagementCheckoutActionsApiClient($config);public function cancelOrder(
string $merchantId,
string $commerceCaseId,
string $checkoutId,
?CancelRequest $cancelRequest = null
): CancelResponseDescription:
Marks items of a Checkout as canceled and automatically cancels the payment associated with those items.
Parameters:
string $merchantId: The unique identifier of the merchant. A Checkout is associated with exactly one merchant.string $commerceCaseId: The unique identifier of a Commerce Case.string $checkoutId: The unique identifier of a Checkout.CancelRequest|null $cancelRequest: The request body containing details for the cancellation (optional).
Returns:
CancelResponse - The response object containing details of the canceled order.
Exceptions:
ApiErrorResponseExceptionApiResponseRetrievalException
public function createOrder(
string $merchantId,
string $commerceCaseId,
string $checkoutId,
OrderRequest $orderRequest
): OrderResponseDescription:
Creates an order that will automatically execute a payment.
Parameters:
string $merchantId: The unique identifier of the merchant. A Checkout is associated with exactly one merchant.string $commerceCaseId: The unique identifier of a Commerce Case.string $checkoutId: The unique identifier of a Checkout.OrderRequest $orderRequest: The request body containing details for creating the order.
Returns:
OrderResponse - The response object containing details of the created order.
Exceptions:
ApiErrorResponseExceptionApiResponseRetrievalException
public function deliverOrder(
string $merchantId,
string $commerceCaseId,
string $checkoutId,
DeliverRequest $deliverRequest
): DeliverResponseDescription:
Marks items of a Checkout as delivered and automatically captures the payment associated with those items.
Parameters:
string $merchantId: The unique identifier of the merchant. A Checkout is associated with exactly one merchant.string $commerceCaseId: The unique identifier of a Commerce Case.string $checkoutId: The unique identifier of a Checkout.DeliverRequest $deliverRequest: The request body containing details for delivering the order.
Returns:
DeliverResponse - The response object containing details of the delivered order.
Exceptions:
ApiErrorResponseExceptionApiResponseRetrievalException
public function returnOrder(
string $merchantId,
string $commerceCaseId,
string $checkoutId,
?ReturnRequest $returnRequest = null
): ReturnResponseDescription:
Marks items of a Checkout as returned and automatically refunds the payment associated with those items.
Parameters:
string $merchantId: The unique identifier of the merchant. A Checkout is associated with exactly one merchant.string $commerceCaseId: The unique identifier of a Commerce Case.string $checkoutId: The unique identifier of a Checkout.ReturnRequest|null $returnRequest: The request body containing details for the return (optional).
Returns:
ReturnResponse - The response object containing details of the returned order.
Exceptions:
ApiErrorResponseExceptionApiResponseRetrievalException
The PaymentExecutionApiClient class provides methods to manage the execution of payments within a commerce case. This includes operations such as creating, canceling, capturing, completing, and refunding payments.
You can create a PaymentExecutionApiClient by providing a CommunicatorConfiguration. All endpoints are directly exposed as methods on the instance.
<?php
use PayoneCommercePlatform\Sdk\ApiClient\PaymentExecutionApiClient;
$config = new CommunicatorConfiguration('API_KEY', 'API_SECRET');
$client = new PaymentExecutionApiClient($config);####### cancelPaymentExecution
public function cancelPaymentExecution(
string $merchantId,
string $commerceCaseId,
string $checkoutId,
string $paymentExecutionId,
CancelPaymentRequest $cancelPaymentRequest
): CancelPaymentResponseDescription:
Cancels a payment that has been previously executed.
Parameters:
string $merchantId: The unique identifier of the merchant.string $commerceCaseId: The unique identifier of a Commerce Case.string $checkoutId: The unique identifier of a Checkout.string $paymentExecutionId: The unique identifier of a payment execution.CancelPaymentRequest $cancelPaymentRequest: The request body containing details for the payment cancellation.
Returns:
CancelPaymentResponse - The response object containing details of the canceled payment.
Exceptions:
ApiErrorResponseExceptionApiResponseRetrievalException
public function capturePaymentExecution(
string $merchantId,
string $commerceCaseId,
string $checkoutId,
string $paymentExecutionId,
CapturePaymentRequest $capturePaymentRequest
): CapturePaymentResponseDescription:
Captures a payment that has been authorized but not yet captured.
Parameters:
string $merchantId: The unique identifier of the merchant.string $commerceCaseId: The unique identifier of a Commerce Case.string $checkoutId: The unique identifier of a Checkout.string $paymentExecutionId: The unique identifier of a payment execution.CapturePaymentRequest $capturePaymentRequest: The request body containing details for the payment capture.
Returns:
CapturePaymentResponse - The response object containing details of the captured payment.
Exceptions:
ApiErrorResponseExceptionApiResponseRetrievalException
public function completePayment(
string $merchantId,
string $commerceCaseId,
string $checkoutId,
string $paymentExecutionId,
CompletePaymentRequest $completePaymentRequest
): CompletePaymentResponseDescription:
Completes a payment that has been partially processed or requires finalization.
Parameters:
string $merchantId: The unique identifier of the merchant.string $commerceCaseId: The unique identifier of a Commerce Case.string $checkoutId: The unique identifier of a Checkout.string $paymentExecutionId: The unique identifier of a payment execution.CompletePaymentRequest $completePaymentRequest: The request body containing details for completing the payment.
Returns:
CompletePaymentResponse - The response object containing details of the completed payment.
Exceptions:
ApiErrorResponseExceptionApiResponseRetrievalException
public function createPayment(
string $merchantId,
string $commerceCaseId,
string $checkoutId,
PaymentExecutionRequest $paymentExecutionRequest
): CreatePaymentResponseDescription:
Creates a new payment execution for a checkout.
Parameters:
string $merchantId: The unique identifier of the merchant.string $commerceCaseId: The unique identifier of a Commerce Case.string $checkoutId: The unique identifier of a Checkout.PaymentExecutionRequest $paymentExecutionRequest: The request body containing details for the payment execution.
Returns:
CreatePaymentResponse - The response object containing details of the created payment execution.
Exceptions:
ApiErrorResponseExceptionApiResponseRetrievalException
public function refundPaymentExecution(
string $merchantId,
string $commerceCaseId,
string $checkoutId,
string $paymentExecutionId,
RefundRequest $refundRequest
): RefundPaymentResponseDescription:
Refunds a payment that has been previously captured.
Parameters:
string $merchantId: The unique identifier of the merchant.string $commerceCaseId: The unique identifier of a Commerce Case.string $checkoutId: The unique identifier of a Checkout.string $paymentExecutionId: The unique identifier of a payment execution.RefundRequest $refundRequest: The request body containing details for the payment refund.
Returns:
RefundPaymentResponse - The response object containing details of the refunded payment.
Exceptions:
ApiErrorResponseExceptionApiResponseRetrievalException
The PaymentInformationApiClient class provides methods to create and retrieve payment information associated with a commerce case and a checkout.
You can create a PaymentInformationApiClient by providing a CommunicatorConfiguration. All endpoints are directly exposed as methods on the instance.
<?php
use PayoneCommercePlatform\Sdk\ApiClient\PaymentInformationApiClient;
$config = new CommunicatorConfiguration('API_KEY', 'API_SECRET');
$client = new PaymentInformationApiClient($config);public function createPaymentInformation(
string $merchantId,
string $commerceCaseId,
string $checkoutId,
PaymentInformationRequest $paymentInformationRequest
): PaymentInformationResponseDescription:
Creates a new payment information record associated with a specific checkout.
Parameters:
string $merchantId: The unique identifier of the merchant.string $commerceCaseId: The unique identifier of a Commerce Case.string $checkoutId: The unique identifier of a Checkout.PaymentInformationRequest $paymentInformationRequest: The request body containing details for creating the payment information.
Returns:
PaymentInformationResponse - The response object containing details of the created payment information.
Exceptions:
ApiErrorResponseExceptionApiResponseRetrievalException
public function getPaymentInformation(
string $merchantId,
string $commerceCaseId,
string $checkoutId,
string $paymentInformationId
): PaymentInformationResponseDescription:
Retrieves details of an existing payment information record associated with a specific checkout.
Parameters:
string $merchantId: The unique identifier of the merchant.string $commerceCaseId: The unique identifier of a Commerce Case.string $checkoutId: The unique identifier of a Checkout.string $paymentInformationId: The unique identifier of the payment information.
Returns:
PaymentInformationResponse - The response object containing details of the payment information.
Exceptions:
ApiErrorResponseExceptionApiResponseRetrievalException
See Contributing
Ensure you have PHP 8.2 or higher installed. You will need composer and xdebug. A pretty version of the coverage report will be placed in coverage, after running composer run-script coverage-report.
This repository consists out of the following components:
- The source code of the SDK itself:
/src - The source code of the unit and integration tests (including the examples):
/tests - The source code for demos is located
examples/*. Make sure to runcomposer installandcomposer dumb-autoloadbefore. Within the specific demo before launching it.
This SDK follows semantic versioning (semver). To relase a new version, create a branch release/X.Y.Z and run prepare_release.sh X.Y.Z. The script automatically updates the SDK_VERSION property within the CommunicatorConfiguration class and the version field in the root composer.json, package.json and package-lock.json file. After that the changes are automatically committed and tagged as vX.Y.Z.
After calling the prepare_release.sh script, it is recommended to manually trigger the changelog generation script (which uses conventional-changelog).
-
Conventional Commit Messages:
- Ensure all commit messages follow the conventional commit format, which helps in automatic changelog generation.
- Commit messages should be in the format:
type(scope): subject.
-
Enforcing Commit Messages:
- We enforce conventional commit messages using Lefthook with commitlint.
- This setup ensures that all commit messages are validated before they are committed.
-
Generate Changelog:
- Run the changelog generation script to update the
CHANGELOG.mdfile:npm run changelog
- Review and commit the updated changelog before proceeding with the release.
- Run the changelog generation script to update the
When the release is ready, a PR should be created for release branch. Select develop as the base branch. After merging into develop, merge develop into main.
Once you've pushed your latest changes to the repository, developers can start using the latest version by pulling it from GitHub. However, to make the release more visible and provide detailed release notes, you can optionally create a GitHub release.
- Navigate to the Releases Page: Go to the "Releases" section of your repository on GitHub.
- Draft a New Release: Click "Draft a new release".
- Tag the Release: Select the version tag that corresponds to the commit you want to release (e.g.,
v0.1.0). If the tag doesn't exist, you can create it here. - Release Title: Add a descriptive title for the release (e.g.,
v0.1.0 - Initial Release). - Auto-Generated Release Notes: GitHub can automatically generate release notes based on merged pull requests and commit history. You can review these notes, adjust the content, and highlight important changes.
- Publish the Release: Once you're satisfied with the release notes, click "Publish release".
Creating a GitHub release is optional but beneficial, as it provides additional context and visibility for your users. Developers can then reference this specific release tag in their composer.json file when adding the package as a dependency.
For detailed guidance, refer to the GitHub documentation on managing releases.
This project is licensed under the MIT License - see the LICENSE file for details.
Thank you for using our SDK for Online Payments! If you have any questions or need further assistance, feel free to open an issue or contact us.