Skip to main content
The PHP SDK provides a robust and flexible way to integrate Dodo Payments into your PHP applications. Built following modern PHP standards with PSR-4 autoloading, it offers extensive test coverage and detailed documentation.
The Dodo Payments PHP API Library is currently in beta. We’re excited for you to experiment with it! Please share any suggestions, bug reports, or feature requests by filing an issue.

​
Installation

Install the SDK using Composer: 
composer require dodopayments/client
The SDK requires PHP 8.1.0 or higher and Composer for dependency management.

​
Quick Start

Initialize the client and create a checkout session: 
<?php

use Dodopayments\Client;

$client = new Client(
  bearerToken: getenv('DODO_PAYMENTS_API_KEY') ?: 'My Bearer Token',
  // use 'https://test.dodopayments.com' for test mode
  baseUrl: 'https://live.dodopayments.com'
);

$checkoutSessionResponse = $client->checkoutSessions->create(
  productCart: [["productID" => "product_id", "quantity" => 1]]
);

var_dump($checkoutSessionResponse->session_id);
Store your API keys securely using environment variables. Never expose them in your codebase or commit them to version control.

​
Core Features

PSR-4 Compliant

Follows PHP Standards Recommendations for modern PHP development

Modern PHP

Built for PHP 8.1+ with type declarations and strict types

Extensive Testing

Comprehensive test coverage for reliability and stability

Exception Handling

Clear exception types for different error scenarios

​
Value Objects

The SDK uses named parameters to specify optional arguments. You can initialize value objects using the static with constructor: 
<?php

use Dodopayments\Customers\AttachExistingCustomer;

// Recommended: Use static 'with' constructor with named parameters
$customer = AttachExistingCustomer::with(customerID: "customer_id");
Builders are also available as an alternative pattern: 
<?php

use Dodopayments\Customers\AttachExistingCustomer;

// Alternative: Use builder pattern
$customer = (new AttachExistingCustomer)->withCustomerID("customer_id");

​
Configuration

​
Retry Configuration

Certain errors are automatically retried 2 times by default with a short exponential backoff. The following errors trigger automatic retries:
  • Connection errors (network connectivity problems)
  • 408 Request Timeout
  • 409 Conflict
  • 429 Rate Limit
  • 500+ Internal errors
  • Timeouts
Configure retry behavior globally or per-request: 
<?php

use Dodopayments\Client;
use Dodopayments\RequestOptions;

// Configure default for all requests (disable retries)
$client = new Client(maxRetries: 0);

// Or, configure per-request
$result = $client->checkoutSessions->create(
  productCart: [["productID" => "product_id", "quantity" => 1]],
  requestOptions: RequestOptions::with(maxRetries: 5),
);

​
Common Operations

​
Create a Checkout Session

Generate a checkout session: 
$session = $client->checkoutSessions->create(
  productCart: [
    ["productID" => "prod_123", "quantity" => 1]
  ],
  returnUrl: "https://yourdomain.com/return"
);

header('Location: ' . $session->url);

​
Manage Customers

Create and retrieve customer information: 
// Create a customer
$customer = $client->customers->create(
  email: "[email protected]",
  name: "John Doe",
  metadata: [
    "user_id" => "12345"
  ]
);

// Retrieve customer
$customer = $client->customers->retrieve("cus_123");
echo "Customer: {$customer->name} ({$customer->email})";

​
Handle Subscriptions

Create and manage recurring subscriptions: 
// Create a subscription
$subscription = $client->subscriptions->create(
  customerID: "cus_123",
  productID: "prod_456",
  priceID: "price_789"
);

// Cancel subscription
$client->subscriptions->cancel($subscription->id);

​
Pagination

Work with paginated list responses: 
$page = $client->payments->list();

var_dump($page);

// Fetch items from the current page
foreach ($page->getItems() as $item) {
  var_dump($item->brand_id);
}

// Auto-paginate: fetch items from all pages
foreach ($page->pagingEachItem() as $item) {
  var_dump($item->brand_id);
}

​
Error Handling

When the library cannot connect to the API or receives a non-success status code (4xx or 5xx), a subclass of APIException is thrown: 
<?php

use Dodopayments\Core\Exceptions\APIConnectionException;
use Dodopayments\Core\Exceptions\RateLimitException;
use Dodopayments\Core\Exceptions\APIStatusException;

try {
  $checkoutSessionResponse = $client->checkoutSessions->create(
    productCart: [["productID" => "product_id", "quantity" => 1]]
  );
} catch (APIConnectionException $e) {
  echo "The server could not be reached", PHP_EOL;
  var_dump($e->getPrevious());
} catch (RateLimitException $_) {
  echo "A 429 status code was received; we should back off a bit.", PHP_EOL;
} catch (APIStatusException $e) {
  echo "Another non-200-range status code was received", PHP_EOL;
  echo $e->getMessage();
}

​
Error Types

CauseError Type
HTTP 400BadRequestException
HTTP 401AuthenticationException
HTTP 403PermissionDeniedException
HTTP 404NotFoundException
HTTP 409ConflictException
HTTP 422UnprocessableEntityException
HTTP 429RateLimitException
HTTP >= 500InternalServerException
Other HTTP errorAPIStatusException
TimeoutAPITimeoutException
Network errorAPIConnectionException
Always wrap API calls in try-catch blocks to handle potential errors gracefully and provide meaningful feedback to users.

​
Advanced Usage

​
Undocumented Endpoints

Make requests to undocumented endpoints: 
<?php

$response = $client->request(
  method: "post",
  path: '/undocumented/endpoint',
  query: ['dog' => 'woof'],
  headers: ['useful-header' => 'interesting-value'],
  body: ['hello' => 'world']
);

​
Undocumented Parameters

Send undocumented parameters to any endpoint or read undocumented response properties: 
<?php

use Dodopayments\RequestOptions;

$checkoutSessionResponse = $client->checkoutSessions->create(
  productCart: [["productID" => "product_id", "quantity" => 1]],
  requestOptions: RequestOptions::with(
    extraQueryParams: ["my_query_parameter" => "value"],
    extraBodyParams: ["my_body_parameter" => "value"],
    extraHeaders: ["my-header" => "value"],
  ),
);
The extra* parameters with the same name override documented parameters.

​
Framework Integration

​
Laravel

Create a service for Laravel applications: 
<?php

namespace App\Services;

use Dodopayments\Client;

class PaymentService
{
    protected $client;

    public function __construct()
    {
        $this->client = new Client(
            bearerToken: config('services.dodo.api_key')
        );
    }

    public function createCheckout(array $items)
    {
        return $this->client->checkoutSessions->create(
            productCart: $items,
            returnUrl: route('checkout.return')
        );
    }
}
Add configuration in config/services.php: 
'dodo' => [
    'api_key' => env('DODO_API_KEY'),
    'environment' => env('DODO_ENVIRONMENT', 'sandbox')
],

​
Symfony

Create a service in Symfony: 
<?php

namespace App\Service;

use Dodopayments\Client;

class DodoPaymentService
{
    private Client $client;

    public function __construct(string $apiKey)
    {
        $this->client = new Client(bearerToken: $apiKey);
    }

    public function createPayment(int $amount, string $currency, string $customerId): object
    {
        return $this->client->payments->create(
            amount: $amount,
            currency: $currency,
            customerID: $customerId
        );
    }
}
Register in config/services.yaml: 
services:
  App\Service\DodoPaymentService:
    arguments:
      $apiKey: "%env(DODO_API_KEY)%"

​
Resources

GitHub Repository

View source code and contribute

API Reference

Complete API documentation

Discord Community

Get help and connect with developers

Report Issues

Report bugs or request features

​
Support

Need help with the PHP SDK?

​
Contributing

We welcome contributions! Check the contributing guidelines to get started.