PHPackages                             gr4vy/gr4vy-php - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [API Development](/categories/api)
4. /
5. gr4vy/gr4vy-php

ActiveLibrary[API Development](/categories/api)

gr4vy/gr4vy-php
===============

v1.5.47(1mo ago)011.9k↓16.7%22MITPHPPHP >=8.2CI passing

Since Jun 18Pushed 1mo ago1 watchersCompare

[ Source](https://github.com/gr4vy/gr4vy-php)[ Packagist](https://packagist.org/packages/gr4vy/gr4vy-php)[ RSS](/packages/gr4vy-gr4vy-php/feed)WikiDiscussions main Synced 1mo ago

READMEChangelog (10)Dependencies (26)Versions (181)Used By (2)

Gr4vy PHP SDK
=============

[](#gr4vy-php-sdk)

Developer-friendly & type-safe PHP SDK specifically catered to leverage the **Gr4vy** API.

 [![Packagist Version](https://camo.githubusercontent.com/39a73226b466dac8cc2aadee3c66ead58a2344af21270635150e912f5c7fcc73/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f67723476792f67723476792d7068703f696e636c7564655f70726572656c6561736573267374796c653d666f722d7468652d6261646765)](https://packagist.org/packages/gr4vy/gr4vy-php) [![](https://camo.githubusercontent.com/096b86187dea2c62026c9750456a53a3e7c20fdd95fa1b55f5cc9a67ebc2078d/68747470733a2f2f637573746f6d2d69636f6e2d6261646765732e64656d6f6c61622e636f6d2f62616467652f2d4275696c742532304279253230537065616b656173792d3231323031353f7374796c653d666f722d7468652d6261646765266c6f676f436f6c6f723d464245333331266c6f676f3d737065616b65617379266c6162656c436f6c6f723d353435343534)](https://www.speakeasy.com/?utm_source=gr4vy/gr4vy-php&utm_campaign=php)

Summary
-------

[](#summary)

Gr4vy Typescript SDK

The official Gr4vy SDK for Typescript provides a convenient way to interact with the Gr4vy API from your server-side application. This SDK allows you to seamlessly integrate Gr4vy's powerful payment orchestration capabilities, including:

- Creating Transactions: Initiate and process payments with various payment methods and services.
- Managing Buyers: Store and manage buyer information securely.
- Storing Payment Methods: Securely store and tokenize payment methods for future use.
- Handling Webhooks: Easily process and respond to webhook events from Gr4vy.
- And much more: Access the full suite of Gr4vy API payment features.

This SDK is designed to simplify development, reduce boilerplate code, and help you get up and running with Gr4vy quickly and efficiently. It handles authentication, request signing, and provides easy-to-use methods for most API endpoints.

Table of Contents
-----------------

[](#table-of-contents)

- [Gr4vy PHP SDK](#gr4vy-php-sdk)
    - [SDK Installation](#sdk-installation)
    - [SDK Example Usage](#sdk-example-usage)
    - [Bearer token generation](#bearer-token-generation)
    - [Embed token generation](#embed-token-generation)
    - [Merchant account ID selection](#merchant-account-id-selection)
    - [Webhooks verification](#webhooks-verification)
    - [Authentication](#authentication)
    - [Available Resources and Operations](#available-resources-and-operations)
    - [Global Parameters](#global-parameters)
    - [Pagination](#pagination)
    - [Retries](#retries)
    - [Error Handling](#error-handling)
    - [Server Selection](#server-selection)
- [Development](#development)
    - [Testing](#testing)
    - [Contributions](#contributions)

SDK Installation
----------------

[](#sdk-installation)

The SDK relies on [Composer](https://getcomposer.org/) to manage its dependencies.

To install the SDK and add it as a dependency to an existing `composer.json` file:

```
composer require "gr4vy/gr4vy-php"
```

SDK Example Usage
-----------------

[](#sdk-example-usage)

### Example

[](#example)

```
declare(strict_types=1);

require 'vendor/autoload.php';

use Gr4vy;
use Gr4vy\Auth;

// Loaded the key from a file, env variable,
// or anywhere else
$privateKey = "...";

$sdk = Gr4vy\SDK::builder()
    ->setId('example')
    ->setServer('sandbox')
    ->setSecuritySource(Auth::withToken($privateKey))
    ->setMerchantAccountId('default')
    ->build();

$response = $sdk->transactions->list();

if ($response->transactions !== null) {
    // handle response
}
```

Important

Please use ` ->setSecuritySource(Auth::withToken($privateKey))` where the documentation mentions `->setSecurity('')`.

Bearer token generation
-----------------------

[](#bearer-token-generation)

Alternatively, you can create a token for use with the SDK or with your own client library.

```
use Gr4vy\Auth;
$token = Auth::getToken($privateKey),
```

> **Note:** This will only create a token once. Use `Auth::withToken` with our SDK to dynamically generate a token for every request.

Embed token generation
----------------------

[](#embed-token-generation)

Alternatively, you can create a token for use with Embed as follows.

```
use Gr4vy;
use Gr4vy\Auth;

// Loaded the key from a file, env variable,
// or anywhere else
$privateKey = "...";

$sdk = Gr4vy\SDK::builder()
    ->setId('example')
    ->setServer('sandbox')
    ->setSecuritySource(Auth::withToken($privateKey))
    ->setMerchantAccountId('default')
    ->build();

$response = $sdk->checkout_sessions.create();

$embedParams = [
    "amount" => 1299,
    "currency" => "AUD",
];

$token = $token = Auth::getEmbedToken(
    privateKey: $privateKey,
    expiresIn: '+1 hour',
    checkoutSessionId: $response->checkoutSession->id,
    embedParams: $embedParams
);
```

> **Note:** This will only create a token once. Use `Auth::withToken` with our SDK to dynamically generate a token for every request.

Merchant account ID selection
-----------------------------

[](#merchant-account-id-selection)

Depending on the key used, you might need to explicitly define a merchant account ID to use. In our API, this uses the `X-GR4VY-MERCHANT-ACCOUNT-ID` header. When using the SDK, you can set the `merchantAccountId`when initializing the SDK.

```
$sdk = Gr4vy\SDK::builder()
    ->setId('example')
    ->setServer('sandbox')
    ->setSecuritySource(Auth::withToken($privateKey))
    ->setMerchantAccountId('your-merchant-account-id')
    ->build();
```

Webhooks verification
---------------------

[](#webhooks-verification)

The SDK makes it easy to verify that incoming webhooks were actually sent by Gr4vy. Once you have configured the webhook subscription with its corresponding secret, that can be verified the following way:

```
use Gr4vy;

// Webhook payload and headers
$payload = "your-webhook-payload";
$secret = "your-webhook-secret";
$signatureHeader = "signatures-from-header";
$timestampHeader = "timestamp-from-header";
$timestampTolerance = 300; // optional, in seconds (default: 0)

try {
    Webhooks::verifyWebhook(
        secret: $secret$,
        payload: $payload,
        signatureHeader: $signatureHeader$,
        timestampHeader: $timestampHeader,
        timestampTolerance: $timestampTolerance
    );
}
catch(Throwable $th$) {
    // handle the exception
}
```

### Parameters

[](#parameters)

- **`payload`**: The raw payload string received in the webhook request.
- **`secret`**: The secret used to sign the webhook. This is provided in your Gr4vy dashboard.
- **`signatureHeader`**: The `X-Gr4vy-Signature` header from the webhook request.
- **`timestampHeader`**: The `X-Gr4vy-Timestamp` header from the webhook request.
- **`timestampTolerance`**: *(Optional)* The maximum allowed difference (in seconds) between the current time and the timestamp in the webhook. Defaults to `0` (no tolerance).

Authentication
--------------

[](#authentication)

### Per-Client Security Schemes

[](#per-client-security-schemes)

This SDK supports the following security scheme globally:

NameTypeScheme`bearerAuth`httpHTTP BearerTo authenticate with the API the `bearerAuth` parameter must be set when initializing the SDK. For example:

```
declare(strict_types=1);

require 'vendor/autoload.php';

use Gr4vy;

$sdk = Gr4vy\SDK::builder()
    ->setSecurity(
        ''
    )
    ->setMerchantAccountId('default')
    ->build();

$accountUpdaterJobCreate = new Gr4vy\AccountUpdaterJobCreate(
    paymentMethodIds: [
        'ef9496d8-53a5-4aad-8ca2-00eb68334389',
        'f29e886e-93cc-4714-b4a3-12b7a718e595',
    ],
);

$response = $sdk->accountUpdater->jobs->create(
    accountUpdaterJobCreate: $accountUpdaterJobCreate
);

if ($response->accountUpdaterJob !== null) {
    // handle response
}
```

Available Resources and Operations
----------------------------------

[](#available-resources-and-operations)

Available methods### [AccountUpdater.Jobs](docs/sdks/jobs/README.md)

[](#accountupdaterjobs)

- [create](docs/sdks/jobs/README.md#create) - Create account updater job

### [AuditLogs](docs/sdks/auditlogs/README.md)

[](#auditlogs)

- [list](docs/sdks/auditlogs/README.md#list) - List audit log entries

### [Buyers](docs/sdks/buyerssdk/README.md)

[](#buyers)

- [list](docs/sdks/buyerssdk/README.md#list) - List all buyers
- [create](docs/sdks/buyerssdk/README.md#create) - Add a buyer
- [get](docs/sdks/buyerssdk/README.md#get) - Get a buyer
- [update](docs/sdks/buyerssdk/README.md#update) - Update a buyer
- [delete](docs/sdks/buyerssdk/README.md#delete) - Delete a buyer

#### [Buyers.GiftCards](docs/sdks/buyersgiftcards/README.md)

[](#buyersgiftcards)

- [list](docs/sdks/buyersgiftcards/README.md#list) - List gift cards for a buyer

#### [Buyers.PaymentMethods](docs/sdks/buyerspaymentmethods/README.md)

[](#buyerspaymentmethods)

- [list](docs/sdks/buyerspaymentmethods/README.md#list) - List payment methods for a buyer

#### [Buyers.ShippingDetails](docs/sdks/buyersshippingdetails/README.md)

[](#buyersshippingdetails)

- [create](docs/sdks/buyersshippingdetails/README.md#create) - Add buyer shipping details
- [list](docs/sdks/buyersshippingdetails/README.md#list) - List a buyer's shipping details
- [get](docs/sdks/buyersshippingdetails/README.md#get) - Get buyer shipping details
- [update](docs/sdks/buyersshippingdetails/README.md#update) - Update a buyer's shipping details
- [delete](docs/sdks/buyersshippingdetails/README.md#delete) - Delete a buyer's shipping details

### [CardSchemeDefinitions](docs/sdks/cardschemedefinitionssdk/README.md)

[](#cardschemedefinitions)

- [list](docs/sdks/cardschemedefinitionssdk/README.md#list) - List card scheme definitions

### [CheckoutSessions](docs/sdks/checkoutsessions/README.md)

[](#checkoutsessions)

- [create](docs/sdks/checkoutsessions/README.md#create) - Create checkout session
- [update](docs/sdks/checkoutsessions/README.md#update) - Update checkout session
- [get](docs/sdks/checkoutsessions/README.md#get) - Get checkout session
- [delete](docs/sdks/checkoutsessions/README.md#delete) - Delete checkout session

### [DigitalWallets](docs/sdks/digitalwalletssdk/README.md)

[](#digitalwallets)

- [create](docs/sdks/digitalwalletssdk/README.md#create) - Register digital wallet
- [list](docs/sdks/digitalwalletssdk/README.md#list) - List digital wallets
- [get](docs/sdks/digitalwalletssdk/README.md#get) - Get digital wallet
- [delete](docs/sdks/digitalwalletssdk/README.md#delete) - Delete digital wallet
- [update](docs/sdks/digitalwalletssdk/README.md#update) - Update digital wallet

#### [DigitalWallets.Domains](docs/sdks/domains/README.md)

[](#digitalwalletsdomains)

- [create](docs/sdks/domains/README.md#create) - Register a digital wallet domain
- [delete](docs/sdks/domains/README.md#delete) - Remove a digital wallet domain

#### [DigitalWallets.Sessions](docs/sdks/sessions/README.md)

[](#digitalwalletssessions)

- [googlePay](docs/sdks/sessions/README.md#googlepay) - Create a Google Pay session
- [applePay](docs/sdks/sessions/README.md#applepay) - Create a Apple Pay session
- [clickToPay](docs/sdks/sessions/README.md#clicktopay) - Create a Click to Pay session

### [GiftCards](docs/sdks/giftcardssdk/README.md)

[](#giftcards)

- [get](docs/sdks/giftcardssdk/README.md#get) - Get gift card
- [delete](docs/sdks/giftcardssdk/README.md#delete) - Delete a gift card
- [create](docs/sdks/giftcardssdk/README.md#create) - Create gift card
- [list](docs/sdks/giftcardssdk/README.md#list) - List gift cards

#### [GiftCards.Balances](docs/sdks/balances/README.md)

[](#giftcardsbalances)

- [list](docs/sdks/balances/README.md#list) - List gift card balances

### [MerchantAccounts](docs/sdks/merchantaccountssdk/README.md)

[](#merchantaccounts)

- [list](docs/sdks/merchantaccountssdk/README.md#list) - List all merchant accounts
- [create](docs/sdks/merchantaccountssdk/README.md#create) - Create a merchant account
- [get](docs/sdks/merchantaccountssdk/README.md#get) - Get a merchant account
- [update](docs/sdks/merchantaccountssdk/README.md#update) - Update a merchant account

#### [MerchantAccounts.ThreeDsConfiguration](docs/sdks/threedsconfiguration/README.md)

[](#merchantaccountsthreedsconfiguration)

- [create](docs/sdks/threedsconfiguration/README.md#create) - Create 3DS configuration for merchant
- [list](docs/sdks/threedsconfiguration/README.md#list) - List 3DS configurations for merchant
- [update](docs/sdks/threedsconfiguration/README.md#update) - Edit 3DS configuration
- [delete](docs/sdks/threedsconfiguration/README.md#delete) - Delete 3DS configuration for a merchant

### [PaymentLinks](docs/sdks/paymentlinkssdk/README.md)

[](#paymentlinks)

- [create](docs/sdks/paymentlinkssdk/README.md#create) - Add a payment link
- [list](docs/sdks/paymentlinkssdk/README.md#list) - List all payment links
- [expire](docs/sdks/paymentlinkssdk/README.md#expire) - Expire a payment link
- [get](docs/sdks/paymentlinkssdk/README.md#get) - Get payment link

### [PaymentMethods](docs/sdks/paymentmethodssdk/README.md)

[](#paymentmethods)

- [list](docs/sdks/paymentmethodssdk/README.md#list) - List all payment methods
- [create](docs/sdks/paymentmethodssdk/README.md#create) - Create payment method
- [get](docs/sdks/paymentmethodssdk/README.md#get) - Get payment method
- [delete](docs/sdks/paymentmethodssdk/README.md#delete) - Delete payment method

#### [PaymentMethods.NetworkTokens](docs/sdks/paymentmethodsnetworktokens/README.md)

[](#paymentmethodsnetworktokens)

- [list](docs/sdks/paymentmethodsnetworktokens/README.md#list) - List network tokens
- [create](docs/sdks/paymentmethodsnetworktokens/README.md#create) - Provision network token
- [suspend](docs/sdks/paymentmethodsnetworktokens/README.md#suspend) - Suspend network token
- [resume](docs/sdks/paymentmethodsnetworktokens/README.md#resume) - Resume network token
- [delete](docs/sdks/paymentmethodsnetworktokens/README.md#delete) - Delete network token

##### [PaymentMethods.NetworkTokens.Cryptogram](docs/sdks/networktokenscryptogram/README.md)

[](#paymentmethodsnetworktokenscryptogram)

- [create](docs/sdks/networktokenscryptogram/README.md#create) - Provision network token cryptogram

#### [PaymentMethods.PaymentServiceTokens](docs/sdks/paymentmethodspaymentservicetokens/README.md)

[](#paymentmethodspaymentservicetokens)

- [list](docs/sdks/paymentmethodspaymentservicetokens/README.md#list) - List payment service tokens
- [create](docs/sdks/paymentmethodspaymentservicetokens/README.md#create) - Create payment service token
- [delete](docs/sdks/paymentmethodspaymentservicetokens/README.md#delete) - Delete payment service token

### [PaymentOptions](docs/sdks/paymentoptionssdk/README.md)

[](#paymentoptions)

- [list](docs/sdks/paymentoptionssdk/README.md#list) - List payment options

### [PaymentServiceDefinitions](docs/sdks/paymentservicedefinitionssdk/README.md)

[](#paymentservicedefinitions)

- [list](docs/sdks/paymentservicedefinitionssdk/README.md#list) - List payment service definitions
- [get](docs/sdks/paymentservicedefinitionssdk/README.md#get) - Get a payment service definition
- [session](docs/sdks/paymentservicedefinitionssdk/README.md#session) - Create a session for a payment service definition

### [PaymentServices](docs/sdks/paymentservicessdk/README.md)

[](#paymentservices)

- [list](docs/sdks/paymentservicessdk/README.md#list) - List payment services
- [create](docs/sdks/paymentservicessdk/README.md#create) - Update a configured payment service
- [get](docs/sdks/paymentservicessdk/README.md#get) - Get payment service
- [update](docs/sdks/paymentservicessdk/README.md#update) - Configure a payment service
- [delete](docs/sdks/paymentservicessdk/README.md#delete) - Delete a configured payment service
- [verify](docs/sdks/paymentservicessdk/README.md#verify) - Verify payment service credentials
- [session](docs/sdks/paymentservicessdk/README.md#session) - Create a session for a payment service definition

### [Payouts](docs/sdks/payouts/README.md)

[](#payouts)

- [list](docs/sdks/payouts/README.md#list) - List payouts created
- [create](docs/sdks/payouts/README.md#create) - Create a payout
- [get](docs/sdks/payouts/README.md#get) - Get a payout

### [Refunds](docs/sdks/refundssdk/README.md)

[](#refunds)

- [get](docs/sdks/refundssdk/README.md#get) - Get refund

### [ReportExecutions](docs/sdks/reportexecutionssdk/README.md)

[](#reportexecutions)

- [list](docs/sdks/reportexecutionssdk/README.md#list) - List executed reports

### [Reports](docs/sdks/reportssdk/README.md)

[](#reports)

- [list](docs/sdks/reportssdk/README.md#list) - List configured reports
- [create](docs/sdks/reportssdk/README.md#create) - Add a report
- [get](docs/sdks/reportssdk/README.md#get) - Get a report
- [put](docs/sdks/reportssdk/README.md#put) - Update a report

#### [Reports.Executions](docs/sdks/executions/README.md)

[](#reportsexecutions)

- [list](docs/sdks/executions/README.md#list) - List executions for report
- [url](docs/sdks/executions/README.md#url) - Create URL for executed report
- [get](docs/sdks/executions/README.md#get) - Get executed report

### [ThreeDsScenarios](docs/sdks/threedsscenarios/README.md)

[](#threedsscenarios)

- [create](docs/sdks/threedsscenarios/README.md#create) - Create a 3DS scenario
- [list](docs/sdks/threedsscenarios/README.md#list) - List 3DS scenario
- [update](docs/sdks/threedsscenarios/README.md#update) - Update a 3DS scenario
- [delete](docs/sdks/threedsscenarios/README.md#delete) - Delete a 3DS scenario

### [Transactions](docs/sdks/transactions/README.md)

[](#transactions)

- [list](docs/sdks/transactions/README.md#list) - List transactions
- [create](docs/sdks/transactions/README.md#create) - Create transaction
- [get](docs/sdks/transactions/README.md#get) - Get transaction
- [update](docs/sdks/transactions/README.md#update) - Manually update a transaction
- [capture](docs/sdks/transactions/README.md#capture) - Capture transaction
- [void](docs/sdks/transactions/README.md#void) - Void transaction
- [cancel](docs/sdks/transactions/README.md#cancel) - Cancel transaction
- [sync](docs/sdks/transactions/README.md#sync) - Sync transaction

#### [Transactions.Actions](docs/sdks/actions/README.md)

[](#transactionsactions)

- [list](docs/sdks/actions/README.md#list) - List transaction Flow rules

#### [Transactions.Events](docs/sdks/events/README.md)

[](#transactionsevents)

- [list](docs/sdks/events/README.md#list) - List transaction events

#### [Transactions.Refunds](docs/sdks/transactionsrefunds/README.md)

[](#transactionsrefunds)

- [list](docs/sdks/transactionsrefunds/README.md#list) - List transaction refunds
- [create](docs/sdks/transactionsrefunds/README.md#create) - Create transaction refund
- [get](docs/sdks/transactionsrefunds/README.md#get) - Get transaction refund

##### [Transactions.Refunds.All](docs/sdks/all/README.md)

[](#transactionsrefundsall)

- [create](docs/sdks/all/README.md#create) - Create batch transaction refund

#### [Transactions.Settlements](docs/sdks/transactionssettlements/README.md)

[](#transactionssettlements)

- [get](docs/sdks/transactionssettlements/README.md#get) - Get transaction settlement
- [list](docs/sdks/transactionssettlements/README.md#list) - List transaction settlements

Global Parameters
-----------------

[](#global-parameters)

A parameter is configured globally. This parameter may be set on the SDK client instance itself during initialization. When configured as an option during SDK initialization, This global value will be used as the default on the operations that use it. When such operations are called, there is a place in each to override the global value, if needed.

For example, you can set `merchant_account_id` to `` at SDK initialization and then you do not have to pass the same value on calls to operations like `get`. But if you want to do so you may, which will locally override the global setting. See the example code below for a demonstration.

### Available Globals

[](#available-globals)

The following global parameter is available.

NameTypeDescriptionmerchantAccountIdstringThe ID of the merchant account to use for this request.### Example

[](#example-1)

```
declare(strict_types=1);

require 'vendor/autoload.php';

use Gr4vy;

$sdk = Gr4vy\SDK::builder()
    ->setMerchantAccountId('default')
    ->setSecurity(
        ''
    )
    ->build();

$response = $sdk->merchantAccounts->get(
    merchantAccountId: 'merchant-12345'
);

if ($response->merchantAccount !== null) {
    // handle response
}
```

Pagination
----------

[](#pagination)

Some of the endpoints in this SDK support pagination. To use pagination, you make your SDK calls as usual, but the returned object will be a `Generator` instead of an individual response.

Working with generators is as simple as iterating over the responses in a `foreach` loop, and you can see an example below:

```
declare(strict_types=1);

require 'vendor/autoload.php';

use Gr4vy;

$sdk = Gr4vy\SDK::builder()
    ->setMerchantAccountId('default')
    ->setSecurity(
        ''
    )
    ->build();

$request = new Gr4vy\ListBuyersRequest(
    cursor: 'ZXhhbXBsZTE',
    search: 'John',
    externalIdentifier: 'buyer-12345',
);

$responses = $sdk->buyers->list(
    request: $request
);

foreach ($responses as $response) {
    if ($response->statusCode === 200) {
        // handle response
    }
}
```

Retries
-------

[](#retries)

Some of the endpoints in this SDK support retries. If you use the SDK without any configuration, it will fall back to the default retry strategy provided by the API. However, the default retry strategy can be overridden on a per-operation basis, or across the entire SDK.

To change the default retry strategy for a single API call, simply provide an `Options` object built with a `RetryConfig` object to the call:

```
declare(strict_types=1);

require 'vendor/autoload.php';

use Gr4vy;
use Gr4vy\Utils\Retry;

$sdk = Gr4vy\SDK::builder()
    ->setMerchantAccountId('default')
    ->setSecurity(
        ''
    )
    ->build();

$request = new Gr4vy\ListBuyersRequest(
    cursor: 'ZXhhbXBsZTE',
    search: 'John',
    externalIdentifier: 'buyer-12345',
);

$responses = $sdk->buyers->list(
    request: $request,
    options: Utils\Options->builder()->setRetryConfig(
        new Retry\RetryConfigBackoff(
            initialInterval: 1,
            maxInterval:     50,
            exponent:        1.1,
            maxElapsedTime:  100,
            retryConnectionErrors: false,
        ))->build()
);

foreach ($responses as $response) {
    if ($response->statusCode === 200) {
        // handle response
    }
}
```

If you'd like to override the default retry strategy for all operations that support retries, you can pass a `RetryConfig` object to the `SDKBuilder->setRetryConfig` function when initializing the SDK:

```
declare(strict_types=1);

require 'vendor/autoload.php';

use Gr4vy;
use Gr4vy\Utils\Retry;

$sdk = Gr4vy\SDK::builder()
    ->setRetryConfig(
        new Retry\RetryConfigBackoff(
            initialInterval: 1,
            maxInterval:     50,
            exponent:        1.1,
            maxElapsedTime:  100,
            retryConnectionErrors: false,
        )
  )
    ->setMerchantAccountId('default')
    ->setSecurity(
        ''
    )
    ->build();

$request = new Gr4vy\ListBuyersRequest(
    cursor: 'ZXhhbXBsZTE',
    search: 'John',
    externalIdentifier: 'buyer-12345',
);

$responses = $sdk->buyers->list(
    request: $request
);

foreach ($responses as $response) {
    if ($response->statusCode === 200) {
        // handle response
    }
}
```

Error Handling
--------------

[](#error-handling)

Handling errors in this SDK should largely match your expectations. All operations return a response object or throw an exception.

By default an API error will raise a `errors\APIException` exception, which has the following properties:

PropertyTypeDescription`$message`*string*The error message`$statusCode`*int*The HTTP status code`$rawResponse`*?\\Psr\\Http\\Message\\ResponseInterface*The raw HTTP response`$body`*string*The response contentWhen custom error responses are specified for an operation, the SDK may also throw their associated exception. You can refer to respective *Errors* tables in SDK docs for more details on possible exception types for each operation. For example, the `create` method throws the following exceptions:

Error TypeStatus CodeContent TypeErrors\\Error400400application/jsonErrors\\Error401401application/jsonErrors\\Error403403application/jsonErrors\\Error404404application/jsonErrors\\Error405405application/jsonErrors\\Error409409application/jsonErrors\\HTTPValidationError422application/jsonErrors\\Error425425application/jsonErrors\\Error429429application/jsonErrors\\Error500500application/jsonErrors\\Error502502application/jsonErrors\\Error504504application/jsonerrors\\APIException4XX, 5XX\*/\*### Example

[](#example-2)

```
declare(strict_types=1);

require 'vendor/autoload.php';

use Gr4vy;
use Gr4vy\Errors;

$sdk = Gr4vy\SDK::builder()
    ->setMerchantAccountId('default')
    ->setSecurity(
        ''
    )
    ->build();

try {
    $accountUpdaterJobCreate = new Gr4vy\AccountUpdaterJobCreate(
        paymentMethodIds: [
            'ef9496d8-53a5-4aad-8ca2-00eb68334389',
            'f29e886e-93cc-4714-b4a3-12b7a718e595',
        ],
    );

    $response = $sdk->accountUpdater->jobs->create(
        accountUpdaterJobCreate: $accountUpdaterJobCreate
    );

    if ($response->accountUpdaterJob !== null) {
        // handle response
    }
} catch (Errors\Error400Throwable $e) {
    // handle $e->$container data
    throw $e;
} catch (Errors\Error401Throwable $e) {
    // handle $e->$container data
    throw $e;
} catch (Errors\Error403Throwable $e) {
    // handle $e->$container data
    throw $e;
} catch (Errors\Error404Throwable $e) {
    // handle $e->$container data
    throw $e;
} catch (Errors\Error405Throwable $e) {
    // handle $e->$container data
    throw $e;
} catch (Errors\Error409Throwable $e) {
    // handle $e->$container data
    throw $e;
} catch (Errors\HTTPValidationErrorThrowable $e) {
    // handle $e->$container data
    throw $e;
} catch (Errors\Error425Throwable $e) {
    // handle $e->$container data
    throw $e;
} catch (Errors\Error429Throwable $e) {
    // handle $e->$container data
    throw $e;
} catch (Errors\Error500Throwable $e) {
    // handle $e->$container data
    throw $e;
} catch (Errors\Error502Throwable $e) {
    // handle $e->$container data
    throw $e;
} catch (Errors\Error504Throwable $e) {
    // handle $e->$container data
    throw $e;
} catch (errors\APIException $e) {
    // handle default exception
    throw $e;
}
```

Server Selection
----------------

[](#server-selection)

### Select Server by Name

[](#select-server-by-name)

You can override the default server globally using the `setServer(string $serverName)` builder method when initializing the SDK client instance. The selected server will then be used as the default on the operations that use it. This table lists the names associated with the available servers:

NameServerVariablesDescription`sandbox``https://api.sandbox.{id}.gr4vy.app``id``production``https://api.{id}.gr4vy.app``id`If the selected server has variables, you may override its default values using the associated builder method(s):

VariableBuilderMethodDefaultDescription`id``setId(string id)``"example"`The subdomain for your Gr4vy instance.#### Example

[](#example-3)

```
declare(strict_types=1);

require 'vendor/autoload.php';

use Gr4vy;

$sdk = Gr4vy\SDK::builder()
    ->setServer('sandbox')
    ->setId('example')
    ->setMerchantAccountId('default')
    ->setSecurity(
        ''
    )
    ->build();

$accountUpdaterJobCreate = new Gr4vy\AccountUpdaterJobCreate(
    paymentMethodIds: [
        'ef9496d8-53a5-4aad-8ca2-00eb68334389',
        'f29e886e-93cc-4714-b4a3-12b7a718e595',
    ],
);

$response = $sdk->accountUpdater->jobs->create(
    accountUpdaterJobCreate: $accountUpdaterJobCreate
);

if ($response->accountUpdaterJob !== null) {
    // handle response
}
```

### Override Server URL Per-Client

[](#override-server-url-per-client)

The default server can also be overridden globally using the `setServerUrl(string $serverUrl)` builder method when initializing the SDK client instance. For example:

```
declare(strict_types=1);

require 'vendor/autoload.php';

use Gr4vy;

$sdk = Gr4vy\SDK::builder()
    ->setServerURL('https://api.sandbox.example.gr4vy.app')
    ->setMerchantAccountId('default')
    ->setSecurity(
        ''
    )
    ->build();

$accountUpdaterJobCreate = new Gr4vy\AccountUpdaterJobCreate(
    paymentMethodIds: [
        'ef9496d8-53a5-4aad-8ca2-00eb68334389',
        'f29e886e-93cc-4714-b4a3-12b7a718e595',
    ],
);

$response = $sdk->accountUpdater->jobs->create(
    accountUpdaterJobCreate: $accountUpdaterJobCreate
);

if ($response->accountUpdaterJob !== null) {
    // handle response
}
```

Development
===========

[](#development)

Testing
-------

[](#testing)

To run the tests, install PHP and compose, ensure to download the `private_key.pem` for the test environment, and run the following.

```
composer install
composer test
```

Additionally, the following tools can be used to lint the code.

```
# autoformat the code
vendor/bin/pint tests src --repair
# static code analysis
vendor/bin/phpstan analyse src tests --level 7 --memory-limit 1G --no-progress --error-format=table
```

Contributions
-------------

[](#contributions)

While we value open-source contributions to this SDK, this library is generated programmatically. Any manual changes added to internal files will be overwritten on the next generation. We look forward to hearing your feedback. Feel free to open a PR or an issue with a proof of concept and we'll do our best to include it in a future release.

### SDK Created by [Speakeasy](https://www.speakeasy.com/?utm_source=gr4vy/gr4vy-php&utm_campaign=php)

[](#sdk-created-by-speakeasy)

###  Health Score

59

—

FairBetter than 99% of packages

Maintenance89

Actively maintained with recent releases

Popularity27

Limited adoption so far

Community22

Small or concentrated contributor base

Maturity83

Battle-tested with a long release history

 Bus Factor1

Top contributor holds 66.2% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~10 days

Recently: every ~2 days

Total

175

Last Release

53d ago

Major Versions

v0.26.0 → v1.0.0-beta.12025-05-22

v0.27.0 → v1.0.32025-06-26

PHP version history (5 changes)v0.1.0PHP >=7.2

v0.13.0PHP >=7.3

v0.24.0PHP >=8.1

v1.0.0-beta.1PHP ^8.2

v1.1.13PHP >=8.2

### Community

Maintainers

![](https://www.gravatar.com/avatar/36af2a7bd876b6cd36d84a155973f5b5311c9b73c4cf793316f86f969dd33143?d=identicon)[cbetta](/maintainers/cbetta)

![](https://www.gravatar.com/avatar/5118ef58968666afd00bd16cd4237f05ee391d0059fbd163cf4cad7e4b3c60aa?d=identicon)[gr4vy-code](/maintainers/gr4vy-code)

---

Top Contributors

[![github-actions[bot]](https://avatars.githubusercontent.com/in/15368?v=4)](https://github.com/github-actions[bot] "github-actions[bot] (133 commits)")[![cbetta](https://avatars.githubusercontent.com/u/7718?v=4)](https://github.com/cbetta "cbetta (44 commits)")[![steve-gr4vy](https://avatars.githubusercontent.com/u/82510386?v=4)](https://github.com/steve-gr4vy "steve-gr4vy (13 commits)")[![phillipgr4vy](https://avatars.githubusercontent.com/u/92320120?v=4)](https://github.com/phillipgr4vy "phillipgr4vy (7 commits)")[![andrewmackett](https://avatars.githubusercontent.com/u/3646992?v=4)](https://github.com/andrewmackett "andrewmackett (1 commits)")[![aliminaei](https://avatars.githubusercontent.com/u/1032699?v=4)](https://github.com/aliminaei "aliminaei (1 commits)")[![renovate[bot]](https://avatars.githubusercontent.com/in/2740?v=4)](https://github.com/renovate[bot] "renovate[bot] (1 commits)")[![alibeylan](https://avatars.githubusercontent.com/u/9335944?v=4)](https://github.com/alibeylan "alibeylan (1 commits)")

---

Tags

gr4vyorchestrationpaymentssdk

###  Code Quality

TestsPHPUnit

Static AnalysisPHPStan

Code StyleLaravel Pint

Type Coverage Yes

### Embed Badge

![Health badge](/badges/gr4vy-gr4vy-php/health.svg)

```
[![Health](https://phpackages.com/badges/gr4vy-gr4vy-php/health.svg)](https://phpackages.com/packages/gr4vy-gr4vy-php)
```

###  Alternatives

[sylius/sylius

E-Commerce platform for PHP, based on Symfony framework.

8.4k5.6M651](/packages/sylius-sylius)[clerkinc/backend-php

2755.0k](/packages/clerkinc-backend-php)[polar-sh/sdk

4014.5k4](/packages/polar-sh-sdk)[wheelpros/fitment-platform-api

Magento 2 (Open Source)

12.1k1.2k](/packages/wheelpros-fitment-platform-api)[fschmtt/keycloak-rest-api-client-php

PHP client to interact with Keycloak's Admin REST API.

4684.7k2](/packages/fschmtt-keycloak-rest-api-client-php)[commercetools/commercetools-sdk

The official PHP SDK for the commercetools Composable Commerce APIs

19281.5k](/packages/commercetools-commercetools-sdk)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)