Referência da API

REST API para pagamentos, assinaturas, clientes e faturamento. Autentique-se com chaves de API e processe webhooks para eventos em tempo real.

SDKs & Libraries

SDKs oficiais de backend para TypeScript, Python, Go, PHP, Java, Kotlin, C#, Ruby e Rust. Essas bibliotecas cuidam da autenticação, serialização e tratamento de erros para que você possa se concentrar na sua integração.

Mobile Checkout SDKs

Abra o checkout hospedado do Dodo em aplicativos Android, iOS, React Native e Flutter e obtenha um resultado tipado em uma única chamada. Esses SDKs não armazenam nenhuma chave de API.

​

URLs de ambiente

• Modo de teste: https://test.dodopayments.com
• Modo de produção: https://live.dodopayments.com

Saiba mais sobre Modo de teste vs Modo ativo.

​

Autenticação

As solicitações de API exigem uma API key, exceto alguns endpoints públicos, como Ativar licença, Validar licença e Desativar licença. Gere uma no seu painel e inclua-a no header Authorization de cada solicitação.

1. Generate an API Key

   Acesse Developer → API Keys no seu dashboard e selecione Add API Key. Crie a chave no modo que deseja usar: uma chave do modo de teste funciona somente com https://test.dodopayments.com, e uma chave do modo de produção funciona somente com https://live.dodopayments.com. Dê à chave um nome descritivo e escolha seu nível de acesso:

   • Enable write access marcada (padrão): permissões completas de leitura e gravação para todas as operações da API.
   • Enable write access desmarcada: acesso somente leitura. Você pode buscar dados (pagamentos, assinaturas, clientes, produtos), mas não pode criar ou modificar recursos.

   Desmarque Enable write access para integrações que precisam apenas visualizar dados, como ferramentas de analytics ou integrações com dashboards.

2. Store Your Key Securely

   Copie a chave imediatamente. Você não poderá vê-la novamente. Armazene-a em uma variável de ambiente, como DODO_PAYMENTS_API_KEY.

3. Authenticate Requests

   Inclua sua chave de API no cabeçalho Authorization de todas as solicitações:

   Authorization: Bearer YOUR_API_KEY
   

   Nunca exponha sua chave de API em código do lado do cliente, repositórios públicos ou sistemas de controle de versão.

​

Formato da resposta

As solicitações bem-sucedidas retornam 200 ou 201 com um corpo JSON, ou 204 sem corpo. Os erros retornam um status 4xx ou 5xx com um corpo JSON que contém um code e um message.

Success

{
  "payment_id": "pay_gr4RizvMOXFJ6xca3y2tU",
  "status": "succeeded",
  "total_amount": 2999,
  "currency": "USD",
  "created_at": "2024-01-15T10:30:00Z"
}

​

Limites de taxa

A API aplica dois limites simultaneamente: um limite de picos por segundo e um limite sustentado por minuto. Os limites se aplicam à sua empresa como um todo, em todas as suas chaves de API, e dependem do nível de limite de taxa da sua empresa.

​

Nível padrão

Janela	Limite
Por segundo (pico)	40 solicitações
Por minuto (sustentado)	240 solicitações

​

Níveis superiores

Empresas com necessidades maiores de API podem fazer upgrade para limites de taxa superiores:

Nível	Pico (por segundo)	Sustentado (por minuto)
Padrão	40	240
Nível 1	100	1.000
Nível 2	500	5.000

Para fazer upgrade do seu nível de limite de taxa, envie um e-mail para [e-mail].

​

Solicitações não autenticadas

As solicitações sem uma chave de API válida têm o limite de taxa definido pelo endereço IP:

Janela	Limite
Por segundo (pico)	20 solicitações
Por minuto (sustentado)	100 solicitações

​

Cabeçalhos de limite de taxa

As respostas incluem cabeçalhos que mostram seu uso atual:

• X-RateLimit-Limit — Número máximo de solicitações permitidas na janela atual.
• X-RateLimit-Remaining — Solicitações restantes antes de atingir o limite.
• X-RateLimit-Reset — Segundos até a redefinição da janela atual.

Quando você excede o limite, a API retorna 429 Too Many Requests. Implemente um backoff exponencial na sua lógica de novas tentativas.

​

Tratamento de erros

Para descobrir o significado de um erro e como resolvê-lo, consulte as páginas de códigos de erro e falhas de transações.

Error Codes

Lista completa de códigos de erro e seus significados.

Transaction Failures

Problemas comuns de transações e como lidar com eles.

​

Webhooks

Receba notificações em tempo real quando pagamentos, assinaturas e outros eventos ocorrerem. Configure webhooks no seu dashboard e processe os eventos necessários para sua integração.

Webhook Guide

Configure webhooks, processe eventos e verifique assinaturas.

​

Guias de integração

Comece com um destes guias para criar sua primeira integração:

One-time Payments

Crie sessões de checkout e links de pagamento e processe pagamentos.

Subscriptions

Configure o faturamento recorrente, gerencie planos e processe eventos do ciclo de vida.

Usage-Based Billing

Mensure o uso e cobre os clientes com base no consumo.

Checkout Sessions

Crie experiências de checkout hospedadas e seguras.