Skip to content

README.md

Latest commit

 

History

History
179 lines (120 loc) · 9.14 KB

README.md

File metadata and controls

179 lines (120 loc) · 9.14 KB
Raw

Checkout.com PHP SDK

build-status Quality Gate Status

build-status GitHub release Latest Stable Version

GitHub license

Getting started

Version 4.0.0 is here!

We improved the initialization of SDK making it easier to understand the available options.
Now NAS accounts are the default instance for the SDK and ABC structure was moved to a previous prefixes.
If you have been using this SDK before, you may find the following important changes:

  • Marketplace module was moved to Accounts module, same for classes and references.
  • In most cases, IDE can help you determine from where to import, but if you’re still having issues don't hesitate to open a ticket.

🚀 Please check in GitHub releases for all the versions available.

📖 Checkout our official documentation.

📚 Check out our official API documentation guide, where you can also find more usage examples.

⚠️ PHP version support

As of v5.0.0, this SDK requires PHP 8.1 or newer. Support for PHP 7.1 and 7.4 has been dropped.

This change is required because the SDK now depends on guzzlehttp/guzzle:^7.4 (and guzzlehttp/promises:^2.0), which require PHP 8.0+. Older Guzzle and PHPUnit releases that supported PHP 7.x are affected by security advisories that make them unsuitable for a payment SDK.

If you are still on PHP 7.x, remain on the latest 4.x release until you can upgrade your runtime to PHP 8.1+.

Composer

{
  "require": {
    "php": ">=8.1",
    "checkout/checkout-sdk-php": "version"
  }
}

How to use the SDK

This SDK can be used with two different pair of API keys provided by Checkout. However, using different API keys imply using specific API features. Please find in the table below the types of keys that can be used within this SDK.

Account System Public Key (example) Secret Key (example)
Default pk_zyxwabcde123pqrstu876vwxyt sk_abcdef98765mnopqr4321ghijk
Previous pk_f3456789-ab12-cd34-ef56-7890ghijklmn sk_hijklmn0-1234-5678-abcd-efgh98765432

Note: sandbox keys have a sbox_ or test_ identifier, for Default and Previous accounts respectively.

PLEASE NEVER SHARE OR PUBLISH YOUR CHECKOUT CREDENTIALS.

If you don't have your own API keys, you can sign up for a test account here.

Subdomain value

Requests must be made through your merchant-specific subdomain (MSSD): the first 8 characters of your client ID (excluding cli_). For example, if your client ID is cli_vkuhvk4vjn2edkps7dfsq6emqm, your subdomain is vkuhvk4v. When environmentSubdomain is set the SDK sends requests to https://vkuhvk4v.api.checkout.com. See Base URLs and API endpoints for further details, and for where to find your unique client ID.

Private Link merchants use their pl- prefixed subdomain (for example pl-vkuhvk4v), which the SDK also accepts.

Default

Default keys client instantiation can be done as follows:

$checkoutApi = CheckoutSdk::builder()->staticKeys()
                    ->publicKey("public_key") // optional, only required for operations related with tokens
                    ->secretKey("secret_key")
                    ->environment(Environment::sandbox()) // or production()
                    ->environmentSubdomain("subdomain") // required, Merchant-specific DNS name, the first 8 characters of your client ID
                    ->logger($logger) //optional, for a custom Logger
                    ->httpClientBuilder($client) // optional, for a custom HTTP client
                    ->build();

$paymentsClient = $checkoutApi->getPaymentsClient();
$paymentsClient->refundPayment("payment_id");

Default OAuth

The SDK supports client credentials OAuth, when initialized as follows:

$checkoutApi = CheckoutSdk::builder()->oAuth()
                    ->clientCredentials("client_id", "client_secret")
                    ->scopes([OAuthScope::$Gateway, OAuthScope::$Vault]) // array of scopes
                    ->environment(Environment::sandbox()) // or production()
                    ->environmentSubdomain("subdomain") // required, Merchant-specific DNS name, the first 8 characters of your client ID
                    ->logger($logger) //optional, for a custom Logger
                    ->httpClientBuilder($client) // optional, for a custom HTTP client
                    ->build();

$paymentsClient = $checkoutApi->getPaymentsClient();
$paymentsClient->refundPayment("payment_id");

Previous

If your pair of keys matches the Previous type, this is how the SDK should be used:

$checkoutApi = CheckoutSdk::builder()
                    ->previous()
                    ->staticKeys()
                    ->environment(Environment::sandbox()) // or production()
                    ->environmentSubdomain("subdomain") // optional, Merchant-specific DNS name
                    ->publicKey("public_key") // optional, only required for operations related with tokens
                    ->secretKey("secret_key")
                    ->logger($logger) //optional, for a custom Logger
                    ->httpClientBuilder($client) // optional, for a custom HTTP client
                    ->build();

$paymentsClient = $checkoutApi->getPaymentsClient();
$paymentsClient->refundPayment("payment_id");

PHP Settings

For operations that require file upload (Disputes or Marketplace) the configuration extension=fileinfo must be enabled in the php.ini. File paths passed to the SDK must be controlled by your application (e.g. from validated uploads); do not use paths taken directly from untrusted user input.

Exception handling

All the API responses that do not fall in the 2** status codes, the SDK will throw a CheckoutApiException.

The exception encapsulates http_metadata and $error_details, if available.

Building from source

Once you check out the code from GitHub, the project can be built using composer:

composer update

The execution of integration tests require the following environment variables set in your system:

  • For default account systems (NAS): CHECKOUT_DEFAULT_PUBLIC_KEY & CHECKOUT_DEFAULT_SECRET_KEY
  • For default account systems (OAuth): CHECKOUT_DEFAULT_OAUTH_CLIENT_ID & CHECKOUT_DEFAULT_OAUTH_CLIENT_SECRET
  • For Previous account systems (ABC): CHECKOUT_PREVIOUS_PUBLIC_KEY & CHECKOUT_PREVIOUS_SECRET_KEY

Legacy domain (emergency use only)

⚠️ Only use if merchant specific sub domains are causing issues. Connecting through your merchant-specific subdomain (see Subdomain value) is the supported way of using the Checkout.com API, and non-subdomain usage will be deprecated.

If, in exceptional circumstances, you cannot use your merchant-specific subdomain, you can explicitly opt out by calling useLegacyDomain() instead of environmentSubdomain(...):

$checkoutApi = CheckoutSdk::builder()->staticKeys()
                    ->secretKey("secret_key")
                    ->environment(Environment::sandbox())
                    ->useLegacyDomain() // deprecated, emergency fallback only
                    ->build();

This routes requests to api.checkout.com (or api.sandbox.checkout.com) and access.checkout.com (or access.sandbox.checkout.com). The method is marked @deprecated. Exactly one of environmentSubdomain(...) or useLegacyDomain() must be set: the SDK throws a CheckoutArgumentException if both, or neither, are set. The Previous (ABC) platform predates merchant-specific subdomains and is exempt from this requirement.

Code of Conduct

Please refer to Code of Conduct

Licensing

MIT