Pular para o conteúdo principal

Pré-requisitos

Para integrar a API de Pagamentos Dodo, você precisará:
  • Uma conta de comerciante Dodo Payments
  • Credenciais da API (chave da API e chave secreta do webhook) do painel

Configuração do Painel

  1. Navegue até o Painel de Pagamentos Dodo
  2. Crie um produto (pagamento único ou assinatura)
  3. Gere sua chave da API:
    • Vá para Desenvolvedor > API
    • Guia Detalhado
    • Copie a chave da API no env nomeado DODO_PAYMENTS_API_KEY
  4. Configure webhooks:
    • Vá para Desenvolvedor > Webhooks
    • Crie uma URL de webhook para notificações de pagamento
    • Copie a chave secreta do webhook no env

Integração

Escolha o caminho de integração que se adapta ao seu caso de uso:
  • Sessões de Checkout (recomendado): Melhor para a maioria das integrações. Crie uma sessão em seu servidor e redirecione os clientes para um checkout seguro e hospedado.
  • Checkout Overlay (embutido): Use quando precisar de uma experiência em página que embute o checkout hospedado em seu site.
  • Links de Pagamento Estáticos: URLs compartilháveis instantaneamente, sem código, para coleta rápida de pagamentos.
  • Links de Pagamento Dinâmicos: Links criados programaticamente. No entanto, as Sessões de Checkout são recomendadas e oferecem mais flexibilidade.

1. Sessões de Checkout

Use Sessões de Checkout para criar uma experiência de checkout segura e hospedada para pagamentos únicos ou assinaturas. Você cria uma sessão em seu servidor e, em seguida, redireciona o cliente para o checkout_url.
As sessões de checkout são válidas por 24 horas por padrão. Se você passar confirm=true, as sessões são válidas por 15 minutos e todos os campos obrigatórios devem ser fornecidos.
1

Criar uma sessão de checkout

Escolha seu SDK preferido ou chame a API REST.
import DodoPayments from 'dodopayments';

const client = new DodoPayments({
  bearerToken: process.env.DODO_PAYMENTS_API_KEY,
  environment: 'test_mode', // defaults to 'live_mode'
});

const session = await client.checkoutSessions.create({
  product_cart: [{ product_id: 'prod_123', quantity: 1 }],
  customer: { email: '[email protected]', name: 'John Doe' },
  return_url: 'https://yourapp.com/checkout/success',
});
2

Redirecionar o cliente para o checkout

Após a criação da sessão, redirecione para o checkout_url para iniciar o fluxo hospedado.
// Example in a browser context
window.location.href = session.checkout_url;
Prefira Sessões de Checkout para a maneira mais rápida e confiável de começar a aceitar pagamentos. Para personalização avançada, consulte o guia completo de Sessões de Checkout e a Referência da API.

2. Checkout Overlay

Para uma experiência de checkout em página sem interrupções, explore nossa integração de Checkout Overlay que permite que os clientes concluam pagamentos sem sair do seu site. Links de pagamento estáticos permitem que você aceite pagamentos rapidamente compartilhando uma URL simples. Você pode personalizar a experiência de checkout passando parâmetros de consulta para preencher automaticamente os detalhes do cliente, controlar campos de formulário e adicionar metadados personalizados.
1

Construa seu link de pagamento

Comece com a URL base e anexe seu ID de produto:
https://checkout.dodopayments.com/buy/{productid}
2

Adicione parâmetros principais

Inclua parâmetros de consulta essenciais:
  • quantity
    integer
    default:"1"
    Número de itens a serem comprados.
  • redirect_url
    string
    required
    URL para redirecionar após a conclusão do pagamento.
A URL de redirecionamento incluirá detalhes do pagamento como parâmetros de consulta, por exemplo:
https://example.com/?payment_id=pay_ts2ySpzg07phGeBZqePbH&status=succeeded
3

Pré-preencher informações do cliente (opcional)

Adicione campos de cliente ou cobrança como parâmetros de consulta para agilizar o checkout.
  • fullName
    string
    Nome completo do cliente (ignorado se firstName ou lastName forem fornecidos).
  • firstName
    string
    Primeiro nome do cliente.
  • lastName
    string
    Último nome do cliente.
  • email
    string
    Endereço de e-mail do cliente.
  • country
    string
    País do cliente.
  • addressLine
    string
    Endereço.
  • city
    string
    Cidade.
  • state
    string
    Estado ou província.
  • zipCode
    string
    Código postal/ZIP.
  • showDiscounts
    boolean
    true ou false
4

Controlar campos de formulário (opcional)

Você pode desabilitar campos específicos para torná-los somente leitura para o cliente. Isso é útil quando você já possui os detalhes do cliente (por exemplo, usuários logados).
Para desabilitar um campo, forneça seu valor e defina a respectiva flag disable… como true:
&[email protected]&disableEmail=true
CampoFlag de DesabilitaçãoParâmetro Obrigatório
Nome CompletodisableFullNamefullName
Primeiro NomedisableFirstNamefirstName
Último NomedisableLastNamelastName
E-maildisableEmailemail
PaísdisableCountrycountry
EndereçodisableAddressLineaddressLine
CidadedisableCitycity
EstadodisableStatestate
Código PostaldisableZipCodezipCode
Desabilitar campos ajuda a evitar alterações acidentais e garante a consistência dos dados.
Definir showDiscounts=false desabilitará e ocultará a seção de descontos no formulário de checkout. Use isso se você quiser impedir que os clientes insiram códigos de cupom ou promoções durante o checkout.
5

Adicionar controles avançados (opcional)

  • paymentCurrency
    string
    Especifica a moeda de pagamento. Por padrão, é a moeda do país de cobrança.
  • showCurrencySelector
    boolean
    default:"true"
    Mostrar ou ocultar o seletor de moeda.
  • paymentAmount
    integer
    Valor em centavos (apenas para preços do tipo Pay What You Want).
  • metadata_*
    string
    Campos de metadados personalizados (por exemplo, metadata_orderId=123).
6

Compartilhar o link

Envie o link de pagamento completo para seu cliente. Quando eles visitarem, todos os parâmetros de consulta são coletados e armazenados com um ID de sessão. A URL é então simplificada para incluir apenas o parâmetro de sessão (por exemplo, ?session=sess_1a2b3c4d). As informações armazenadas persistem através de atualizações de página e são acessíveis durante todo o processo de checkout.
A experiência de checkout do cliente agora está simplificada e personalizada com base em seus parâmetros.
Prefira Sessões de Checkout para a maioria dos casos de uso, pois oferecem mais flexibilidade e controle.
Criados via chamada de API ou nosso SDK com detalhes do cliente. Aqui está um exemplo: Existem duas APIs para criar links de pagamento dinâmicos: O guia abaixo é para a criação de links de pagamento únicos. Para instruções detalhadas sobre a integração de assinaturas, consulte este Guia de Integração de Assinaturas.
Certifique-se de que você está passando payment_link = true para obter o link de pagamento
import DodoPayments from 'dodopayments';

const client = new DodoPayments({
bearerToken: process.env['DODO_PAYMENTS_API_KEY'], // This is the default and can be omitted
environment: 'test_mode', // defaults to 'live_mode'
});

async function main() {
const payment = await client.payments.create({
payment_link: true,
billing: { city: 'city', country: 'AF', state: 'state', street: 'street', zipcode: 0 },
customer: { email: '[email protected]', name: 'name' },
product_cart: [{ product_id: 'product_id', quantity: 0 }],
});

console.log(payment.payment_id);
}

main();
Após criar o link de pagamento, redirecione seus clientes para concluir o pagamento.

Implementando Webhooks

Configure um endpoint de API para receber notificações de pagamento. Aqui está um exemplo usando Next.js:
import { Webhook } from "standardwebhooks";
import { headers } from "next/headers";
import { WebhookPayload } from "@/types/api-types";

const webhook = new Webhook(process.env.DODO_WEBHOOK_KEY!); // Replace with your secret key generated from the Dodo Payments Dashboard

export async function POST(request: Request) {
  const headersList = headers();
  const rawBody = await request.text();

  const webhookHeaders = {
    "webhook-id": headersList.get("webhook-id") || "",
    "webhook-signature": headersList.get("webhook-signature") || "",
    "webhook-timestamp": headersList.get("webhook-timestamp") || "",
  };

  await webhook.verify(rawBody, webhookHeaders);
  const payload = JSON.parse(rawBody) as WebhookPayload;
  
  // Process the payload according to your business logic
}
Nossa implementação de webhook segue a especificação de Webhooks Padrão. Para definições de tipos de webhook, consulte nosso Guia de Eventos de Webhook. Você pode consultar este projeto com implementação de demonstração no GitHub usando Next.js e TypeScript. Você pode conferir a implementação ao vivo aqui.