Pular para o conteúdo principal

Documentation Index

Fetch the complete documentation index at: https://docs.dodopayments.com/llms.txt

Use this file to discover all available pages before exploring further.

O SDK PHP fornece uma maneira robusta e flexível de integrar os pagamentos Dodo em suas aplicações PHP. Construído seguindo os padrões modernos de PHP com autoloading PSR-4, oferece ampla cobertura de testes e documentação detalhada.

​
Instalação

Instale o SDK usando o Composer: 
composer require "dodopayments/client 6.7.1"
O SDK requer PHP 8.1.0 ou superior e o Composer para gerenciamento de dependências.

​
Início Rápido

Inicialize o cliente e crie uma sessão de checkout: 
<?php

use Dodopayments\Client;

$client = new Client(
  bearerToken: getenv('DODO_PAYMENTS_API_KEY') ?: 'My Bearer Token',
  environment: 'test_mode',
);

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

var_dump($checkoutSessionResponse->session_id);
Armazene suas chaves de API com segurança usando variáveis de ambiente. Nunca as exponha no seu código-fonte ou as comite no controle de versão.

​
Recursos Principais

PSR-4 Compliant

Segue as Recomendações de Padrões PHP para desenvolvimento PHP moderno

Modern PHP

Criado para PHP 8.1+ com declarações de tipo e tipos estritos

Extensive Testing

Cobertura abrangente de testes para confiabilidade e estabilidade

Exception Handling

Tipos claros de exceções para diferentes cenários de erro

​
Objetos de Valor

O SDK usa parâmetros nomeados para especificar argumentos opcionais. Você pode inicializar objetos de valor usando o construtor estático with: 
<?php

use Dodopayments\Customers\AttachExistingCustomer;

// Recommended: Use static 'with' constructor with named parameters
$customer = AttachExistingCustomer::with(customerID: "customer_id");
Construtores também estão disponíveis como um padrão alternativo: 
<?php

use Dodopayments\Customers\AttachExistingCustomer;

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

​
Configuração

​
Configuração de Retentativas

Certos erros são automaticamente retentados 2 vezes por padrão com um pequeno atraso exponencial. Os seguintes erros acionam retentativas automáticas:
  • Erros de conexão (problemas de conectividade de rede)
  • 408 Timeout da Requisição
  • 409 Conflito
  • 429 Limite de Taxa
  • 500+ Erros internos
  • Timeouts
Configure o comportamento de retentativa globalmente ou por solicitação: 
<?php

use Dodopayments\Client;

// Configure default for all requests (disable retries)
$client = new Client(requestOptions: ['maxRetries' => 0]);

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

​
Operações Comuns

​
Criar uma Sessão de Checkout

Gere uma sessão de checkout: 
$session = $client->checkoutSessions->create(
  productCart: [
    ["productID" => "prod_123", "quantity" => 1]
  ],
  returnUrl: "https://yourdomain.com/return"
);

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

​
Gerenciar Clientes

Crie e recupere informações de clientes: 
// Create a customer
$customer = $client->customers->create(
  email: "customer@example.com",
  name: "John Doe",
  metadata: [
    "user_id" => "12345"
  ]
);

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

​
Gerenciar Assinaturas

Crie e gerencie assinaturas recorrentes: 
use Dodopayments\Customers\AttachExistingCustomer;
use Dodopayments\Payments\BillingAddress;

// Create a subscription
$subscription = $client->subscriptions->create(
  billing: BillingAddress::with(
    country: 'US',
    city: 'San Francisco',
    state: 'CA',
    street: '1 Market St',
    zipcode: '94105',
  ),
  customer: AttachExistingCustomer::with(customerID: 'cus_123'),
  productID: 'pdt_456',
  quantity: 1,
);

// Charge an on-demand subscription
// productPrice is in the lowest currency denomination (e.g., 2500 = $25.00 USD)
$charge = $client->subscriptions->charge(
  $subscription->subscription_id,
  productPrice: 2500,
);
billing requer no mínimo o código country de dois dígitos ISO. Passe AttachExistingCustomer::with(customerID: '...') para anexar um cliente existente, ou NewCustomer::with(email: '...', name: '...') para criar um. productPrice está na menor denominação de moeda.

​
Paginação

Trabalhe com respostas de lista paginadas: 
$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);
}

​
Tratamento de Erros

Quando a biblioteca não consegue se conectar à API ou recebe um código de status de não-sucesso (4xx ou 5xx), uma subclasse de APIException é lançada: 
<?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();
}

​
Tipos de Erro

MotivoTipo de Erro
HTTP 400BadRequestException
HTTP 401AuthenticationException
HTTP 403PermissionDeniedException
HTTP 404NotFoundException
HTTP 409ConflictException
HTTP 422UnprocessableEntityException
HTTP 429RateLimitException
HTTP >= 500InternalServerException
Outro erro HTTPAPIStatusException
TimeoutAPITimeoutException
Erro de redeAPIConnectionException
Sempre envolva chamadas de API em blocos try-catch para tratar erros potenciais de forma elegante e fornecer feedback significativo aos usuários.

​
Uso Avançado

​
Endpoints Não Documentados

Faça solicitações para endpoints não documentados: 
<?php

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

​
Parâmetros Não Documentados

Envie parâmetros não documentados para qualquer endpoint ou leia propriedades de resposta não documentadas: 
<?php

use Dodopayments\RequestOptions;

$checkoutSessionResponse = $client->checkoutSessions->create(
  productCart: [["productID" => "product_id", "quantity" => 1]],
  requestOptions: [
    'extraQueryParams' => ["my_query_parameter" => "value"],
    'extraBodyParams' => ["my_body_parameter" => "value"],
    'extraHeaders' => ["my-header" => "value"],
  ],
);
Os parâmetros extra* com o mesmo nome substituem os parâmetros documentados.

​
Integração de Framework

​
Laravel

Crie um serviço para aplicações Laravel: 
<?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')
        );
    }
}
Adicione a configuração em config/services.php: 
'dodo' => [
    'api_key' => env('DODO_API_KEY'),
    'environment' => env('DODO_ENVIRONMENT', 'sandbox')
],

​
Symfony

Crie um serviço no 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
        );
    }
}
Registre em config/services.yaml: 
services:
  App\Service\DodoPaymentService:
    arguments:
      $apiKey: "%env(DODO_API_KEY)%"

​
Recursos

GitHub Repository

Veja o código-fonte e contribua

API Reference

Documentação completa da API

Discord Community

Obtenha ajuda e conecte-se com desenvolvedores

Report Issues

Relate bugs ou solicite funcionalidades

​
Suporte

Precisa de ajuda com o PHP SDK?

​
Contribuindo

Aceitamos contribuições! Confira as diretrizes de contribuição para começar.
Last modified on May 14, 2026