Adaptador para Nuxt

Integre Dodo Payments ao seu projeto Nuxt usando o módulo oficial do Nuxt. Abrange checkout, portal do cliente, webhooks e configuração segura do ambiente.

Checkout API Route

Integre o checkout do Dodo Payments ao seu aplicativo Nuxt usando uma rota de servidor.

Customer Portal API Route

Permita que os clientes gerenciem assinaturas e dados por meio de uma rota de servidor do Nuxt.

Webhooks API Route

Receba e processe eventos de webhook do Dodo Payments com segurança no Nuxt.

​

Visão geral

Este guia explica como integrar o Dodo Payments ao seu aplicativo Nuxt usando o módulo oficial do Nuxt. Você aprenderá a configurar as rotas de API de checkout, portal do cliente e webhook, além de gerenciar variáveis de ambiente com segurança.

​

Instalação

1. Install the Nuxt module

   Execute o comando a seguir na raiz do projeto:

   npm install @dodopayments/nuxt
   
2. Register the module in nuxt.config.ts

   Adicione @dodopayments/nuxt ao seu array modules e configure-o:

   nuxt.config.ts

   export default defineNuxtConfig({
     modules: ["@dodopayments/nuxt"],
     devtools: { enabled: true },
     compatibilityDate: "2025-02-25",
     runtimeConfig: {
       private: {
         bearerToken: process.env.NUXT_PRIVATE_BEARER_TOKEN,
         webhookKey: process.env.NUXT_PRIVATE_WEBHOOK_KEY,
         environment: process.env.NUXT_PRIVATE_ENVIRONMENT,
         returnUrl: process.env.NUXT_PRIVATE_RETURNURL
       },
     }
   });
   

Nunca faça commit do arquivo .env ou de segredos no controle de versão.

​

Exemplos de manipuladores de rotas de API

Todas as integrações com Dodo Payments no Nuxt são gerenciadas por meio de rotas de servidor no diretório server/routes/api/.

Checkout API Route

Use este manipulador para integrar o checkout do Dodo Payments ao seu aplicativo Nuxt. Compatível com fluxos de pagamento estáticos (GET), dinâmicos (POST) e de sessão (POST).

server/routes/api/checkout.get.ts

export default defineEventHandler((event) => {
  const {
    private: { bearerToken, environment, returnUrl },
  } = useRuntimeConfig();

  const handler = checkoutHandler({
    bearerToken: bearerToken,
    environment: environment,
    returnUrl: returnUrl,
  });

  return handler(event);
});

server/routes/api/checkout.post.ts

export default defineEventHandler((event) => {
  const {
    private: { bearerToken, environment, returnUrl },
  } = useRuntimeConfig();

  const handler = checkoutHandler({
    bearerToken: bearerToken,
    environment: environment,
    returnUrl: returnUrl,
    type: "dynamic"
  });

  return handler(event);
});

server/routes/api/checkout.post.ts (Checkout Sessions)

export default defineEventHandler((event) => {
  const {
    private: { bearerToken, environment, returnUrl },
  } = useRuntimeConfig();

  const handler = checkoutHandler({
    bearerToken: bearerToken,
    environment: environment,
    returnUrl: returnUrl,
    type: "session"
  });

  return handler(event);
});

Se productId estiver ausente ou for inválido, o manipulador retornará uma resposta 400.

Static Checkout Curl example

curl --request GET \
--url 'https://example.com/api/checkout?productId=pdt_fqJhl7pxKWiLhwQR042rh' \
--header 'User-Agent: insomnia/11.2.0' \
--cookie mode=test

Dynamic Checkout Curl example

curl --request POST \
--url https://example.com/api/checkout \
--header 'Content-Type: application/json' \
--header 'User-Agent: insomnia/11.2.0' \
--cookie mode=test \
--data '{
"billing": {
  "city": "Texas",
  "country": "US",
  "state": "Texas",
  "street": "56, hhh",
  "zipcode": "560000"
},
"customer": {
  "email": "[e-mail]",
  	"name": "test"
},
"metadata": {},
"payment_link": true,
  "product_id": "pdt_QMDuvLkbVzCRWRQjLNcs",
  "quantity": 1,
  "billing_currency": "USD",
  "discount_codes": ["IKHZ23M9GQ"],
  "return_url": "https://example.com",
  "trial_period_days": 10
}'

Checkout Session Curl example

curl --request POST \
--url https://example.com/api/checkout \
--header 'Content-Type: application/json' \
--header 'User-Agent: insomnia/11.2.0' \
--cookie mode=test \
--data '{
"product_cart": [
  {
    "product_id": "pdt_QMDuvLkbVzCRWRQjLNcs",
    "quantity": 1
  }
],
"customer": {
  "email": "[e-mail]",
  "name": "test"
},
"return_url": "https://example.com/success"
}'

Customer Portal API Route

Crie uma rota GET para permitir que os clientes acessem o portal. Aceita customer_id como parâmetro de consulta.

server/routes/api/customer-portal.get.ts

export default defineEventHandler((event) => {
  const {
    private: { bearerToken, environment },
  } = useRuntimeConfig();

  const handler = customerPortalHandler({
    bearerToken,
    environment: environment,
  });

  return handler(event);
});

Parâmetros de consulta:

• customer_id (obrigatório): o ID do cliente para a sessão do portal (por exemplo, ?customer_id=cus_123)
• send_email (opcional, booleano): se true, envia um e-mail ao cliente com o link do portal.

Retorna 400 se customer_id estiver ausente.

Customer Portal Curl example

curl --request GET \
--url 'https://example.com/api/customer-portal?customer_id=cus_9VuW4K7O3GHwasENg31m&send_email=true' \
--header 'User-Agent: insomnia/11.2.0' \
--cookie mode=test

Webhook API Route

Crie uma rota POST para receber e processar com segurança eventos de webhook do Dodo Payments.

server/routes/api/webhook.post.ts

export default defineEventHandler((event) => {
  const {
    private: { webhookKey },
  } = useRuntimeConfig();

  const handler = Webhooks({
    webhookKey: webhookKey,
    onPayload: async (payload: any) => {
      // Handle webhook payload here
    },
    // ...add other event handlers as needed
  });

  return handler(event);
});

​

Manipulador de rota de checkout

O Dodo Payments é compatível com três tipos de fluxos de pagamento para integrar pagamentos ao seu site; este adaptador é compatível com todos os tipos de fluxos de pagamento.

• Links de pagamento estáticos: URLs compartilháveis instantaneamente para coleta rápida de pagamentos sem código.
• Links de pagamento dinâmicos: gere links de pagamento programaticamente com detalhes personalizados usando a API ou SDKs.
• Sessões de checkout: crie experiências de checkout seguras e personalizáveis com carrinhos de produtos e dados do cliente pré-configurados.

Static Checkout (GET)

​

Parâmetros de consulta compatíveis

productId · string · obrigatório

Identificador do produto (por exemplo, ?productId=pdt_nZuwz45WAs64n3l07zpQR).

quantity · integer

Quantidade do produto.

fullName · string

Nome completo do cliente.

firstName · string

Primeiro nome do cliente.

lastName · string

Sobrenome do cliente.

email · string

Endereço de e-mail do cliente.

country · string

País do cliente.

addressLine · string

Linha de endereço do cliente.

city · string

Cidade do cliente.

state · string

Estado/província do cliente.

zipCode · string

CEP/código postal do cliente.

disableFullName · boolean

Desabilita o campo de nome completo.

disableFirstName · boolean

Desabilita o campo de primeiro nome.

disableLastName · boolean

Desabilita o campo de sobrenome.

disableEmail · boolean

Desabilita o campo de e-mail.

disableCountry · boolean

Desabilita o campo de país.

disableAddressLine · boolean

Desabilita a linha de endereço.

disableCity · boolean

Desabilita o campo de cidade.

disableState · boolean

Desabilita o campo de estado.

disableZipCode · boolean

Desabilita o campo de CEP.

paymentCurrency · string

Especifica a moeda do pagamento (por exemplo, USD).

showCurrencySelector · boolean

Exibe o seletor de moeda.

paymentAmount · integer

Especifica o valor do pagamento (por exemplo, 1000 para US$ 10,00).

showDiscounts · boolean

Exibe campos de desconto.

metadata_* · string

Qualquer parâmetro de consulta que comece com metadata_ será passado como metadado.

Se productId estiver ausente, o manipulador retornará uma resposta 400. Parâmetros de consulta inválidos também resultarão em uma resposta 400.

​

Formato da resposta

O checkout estático retorna uma resposta JSON com a URL do checkout:

{
  "checkout_url": "https://checkout.dodopayments.com/..."
}

Dynamic Checkout (POST)

• Envie os parâmetros como um corpo JSON em uma solicitação POST.
• Compatível com pagamentos únicos e recorrentes.
• Para obter uma lista completa dos campos compatíveis no corpo da solicitação POST, consulte:
  • Corpo da solicitação para um produto de pagamento único
  • Corpo da solicitação para um produto de assinatura

​

Formato da resposta

O checkout dinâmico retorna uma resposta JSON com a URL do checkout:

{
  "checkout_url": "https://checkout.dodopayments.com/..."
}

Checkout Sessions (POST)

As sessões de checkout oferecem uma experiência de checkout hospedada e mais segura, que gerencia todo o fluxo de pagamento para compras únicas e assinaturas, com controle completo de personalização.

Consulte o Guia de integração das sessões de checkout para obter mais detalhes e uma lista completa dos campos compatíveis.

​

Formato da resposta

As sessões de checkout retornam uma resposta JSON com a URL do checkout:

{
  "checkout_url": "https://checkout.dodopayments.com/session/..."
}

​

Manipulador de rota do Customer Portal

O manipulador de rota Customer Portal permite integrar perfeitamente o portal do cliente do Dodo Payments ao seu aplicativo Nuxt.

​

Parâmetros de consulta

customer_id · string · obrigatório

O ID do cliente para a sessão do portal (por exemplo, ?customer_id=cus_123).

send_email · boolean

Se definido como true, envia um e-mail ao cliente com o link do portal.

Retorna 400 se customer_id estiver ausente.

​

Manipulador de rota de webhook

• Método: somente solicitações POST são compatíveis. Outros métodos retornam 405.
• Verificação da assinatura: verifica a assinatura do webhook usando webhookKey. Retorna 401 se a verificação falhar.
• Validação do payload: validado com Zod. Retorna 400 para payloads inválidos.
• Tratamento de erros:
  • 401: assinatura inválida
  • 400: payload inválido
  • 500: erro interno durante a verificação
• Roteamento de eventos: chama o manipulador de eventos apropriado com base no tipo de payload.

​

Manipuladores de eventos de webhook compatíveis

Typescript

onPayload?: (payload: WebhookPayload) => Promise<void>;
onPaymentSucceeded?: (payload: WebhookPayload) => Promise<void>;
onPaymentFailed?: (payload: WebhookPayload) => Promise<void>;
onPaymentProcessing?: (payload: WebhookPayload) => Promise<void>;
onPaymentCancelled?: (payload: WebhookPayload) => Promise<void>;
onRefundSucceeded?: (payload: WebhookPayload) => Promise<void>;
onRefundFailed?: (payload: WebhookPayload) => Promise<void>;
onDisputeOpened?: (payload: WebhookPayload) => Promise<void>;
onDisputeExpired?: (payload: WebhookPayload) => Promise<void>;
onDisputeAccepted?: (payload: WebhookPayload) => Promise<void>;
onDisputeCancelled?: (payload: WebhookPayload) => Promise<void>;
onDisputeChallenged?: (payload: WebhookPayload) => Promise<void>;
onDisputeWon?: (payload: WebhookPayload) => Promise<void>;
onDisputeLost?: (payload: WebhookPayload) => Promise<void>;
onSubscriptionActive?: (payload: WebhookPayload) => Promise<void>;
onSubscriptionOnHold?: (payload: WebhookPayload) => Promise<void>;
onSubscriptionRenewed?: (payload: WebhookPayload) => Promise<void>;
onSubscriptionPlanChanged?: (payload: WebhookPayload) => Promise<void>;
onSubscriptionCancelled?: (payload: WebhookPayload) => Promise<void>;
onSubscriptionFailed?: (payload: WebhookPayload) => Promise<void>;
onSubscriptionExpired?: (payload: WebhookPayload) => Promise<void>;
onSubscriptionUpdated?: (payload: WebhookPayload) => Promise<void>;
onLicenseKeyCreated?: (payload: WebhookPayload) => Promise<void>;
onAbandonedCheckoutDetected?: (payload: WebhookPayload) => Promise<void>;
onAbandonedCheckoutRecovered?: (payload: WebhookPayload) => Promise<void>;
onDunningStarted?: (payload: WebhookPayload) => Promise<void>;
onDunningRecovered?: (payload: WebhookPayload) => Promise<void>;
onCreditAdded?: (payload: WebhookPayload) => Promise<void>;
onCreditDeducted?: (payload: WebhookPayload) => Promise<void>;
onCreditExpired?: (payload: WebhookPayload) => Promise<void>;
onCreditRolledOver?: (payload: WebhookPayload) => Promise<void>;
onCreditRolloverForfeited?: (payload: WebhookPayload) => Promise<void>;
onCreditOverageCharged?: (payload: WebhookPayload) => Promise<void>;
onCreditManualAdjustment?: (payload: WebhookPayload) => Promise<void>;
onCreditBalanceLow?: (payload: WebhookPayload) => Promise<void>;

---

​

Prompt para LLM

You are an expert Nuxt developer assistant. Your task is to guide a user through integrating the @dodopayments/nuxt module into their existing Nuxt project.

The @dodopayments/nuxt module provides API route handlers for Dodo Payments' Checkout, Customer Portal, and Webhook functionalities, designed for Nuxt 3 server routes.

First, install the necessary package:

npm install @dodopayments/nuxt

Second, add the configuration to nuxt.config.ts

export default defineNuxtConfig({
  modules: ["@dodopayments/nuxt"],
  devtools: { enabled: true },
  compatibilityDate: "2025-02-25",
  runtimeConfig: {
    private: {
      bearerToken: process.env.NUXT_PRIVATE_BEARER_TOKEN,
      webhookKey: process.env.NUXT_PRIVATE_BEARER_TOKEN,
      environment: process.env.NUXT_PRIVATE_ENVIRONMENT,
      returnUrl: process.env.NUXT_PRIVATE_RETURNURL
    },
  }
});

Here's how you should structure your response:

    Ask the user which functionalities they want to integrate.

"Which parts of the @dodopayments/nuxt module would you like to integrate into your project? You can choose one or more of the following:

    Checkout API Route (for handling product checkouts)
    Customer Portal API Route (for managing customer subscriptions/details)
    Webhook API Route (for receiving Dodo Payments webhook events)
    All (integrate all three)"

    Based on the user's selection, provide detailed integration steps for each chosen functionality.

If Checkout API Route is selected:

Purpose: This route redirects users to the Dodo Payments checkout page.
File Creation: Create a new file at server/routes/api/checkout.get.ts in your Nuxt project.

Code Snippet:

// server/routes/api/checkout.get.ts

export default defineEventHandler((event) => {
  const {
    private: { bearerToken, environment, returnUrl },
  } = useRuntimeConfig();

  const handler = checkoutHandler({
    bearerToken: bearerToken,
    environment: environment,
    returnUrl: returnUrl,
  });

  return handler(event);
});

Configuration & Usage:
- bearerToken: Your Dodo Payments API key. Set via the NUXT_PRIVATE_BEARER_TOKEN environment variable.
- returnUrl: (Optional) The URL to redirect the user to after a successful checkout.
- environment: (Optional) Set to your environment (e.g., "test_mode" or "live_mode").

Static Checkout (GET) Query Parameters:
- productId (required): Product identifier (e.g., ?productId=pdt_nZuwz45WAs64n3l07zpQR)
- quantity (optional): Quantity of the product
- Customer Fields (optional): fullName, firstName, lastName, email, country, addressLine, city, state, zipCode
- Disable Flags (optional, set to true to disable): disableFullName, disableFirstName, disableLastName, disableEmail, disableCountry, disableAddressLine, disableCity, disableState, disableZipCode
- Advanced Controls (optional): paymentCurrency, showCurrencySelector, paymentAmount, showDiscounts
- Metadata (optional): Any query parameter starting with metadata_ (e.g., ?metadata_userId=abc123)

Dynamic Checkout (POST): Parameters are sent as a JSON body. Supports both one-time and recurring payments. For a complete list of supported POST body fields, refer to:
- Docs - One Time Payment Product: https://docs.dodopayments.com/api-reference/payments/post-payments
- Docs - Subscription Product: https://docs.dodopayments.com/api-reference/subscriptions/post-subscriptions

Checkout Sessions (POST) - (Recommended) A more customizable checkout experience. Returns JSON with checkout_url: Parameters are sent as a JSON body. Supports both one-time and recurring payments. Returns: {"checkout_url": "https://checkout.dodopayments.com/session/..."}. For a complete list of supported fields, refer to:

  Checkout Sessions Integration Guide: https://docs.dodopayments.com/developer-resources/checkout-session

Error Handling: If productId is missing or other query parameters are invalid, the handler will return a 400 response.

If Customer Portal API Route is selected:

Purpose: This route allows customers to access their Dodo Payments customer portal.
File Creation: Create a new file at server/routes/api/customer-portal.get.ts in your Nuxt project.

Code Snippet:

// server/routes/api/customer-portal.get.ts

export default defineEventHandler((event) => {
  const {
    private: { bearerToken, environment },
  } = useRuntimeConfig();

  const handler = customerPortalHandler({
    bearerToken,
    environment: environment,
  });

  return handler(event);
});

Query Parameters:
- customer_id (required): The customer ID for the portal session (e.g., ?customer_id=cus_123)
- send_email (optional, boolean): If set to true, sends an email to the customer with the portal link.
- Returns 400 if customer_id is missing.

If Webhook API Route is selected:

Purpose: This route processes incoming webhook events from Dodo Payments, allowing your application to react to events like successful payments, refunds, or subscription changes.
File Creation: Create a new file at server/routes/api/webhook.post.ts in your Nuxt project.

Code Snippet:

// server/routes/api/webhook.post.ts

export default defineEventHandler((event) => {
  const {
    private: { webhookKey },
  } = useRuntimeConfig();

  const handler = Webhooks({
    webhookKey: webhookKey,
    onPayload: async (payload) => {
      // handle the payload
    },
    // ... other event handlers for granular control
  });

  return handler(event);
});

Handler Details:
- Method: Only POST requests are supported. Other methods return 405.
- Signature Verification: The handler verifies the webhook signature using webhookKey and returns 401 if verification fails.
- Payload Validation: The payload is validated with Zod. Returns 400 for invalid payloads.

Error Handling:
- 401: Invalid signature
- 400: Invalid payload
- 500: Internal error during verification

Event Routing: Calls the appropriate event handler based on the payload type. Supported event handlers include:
- onPayload?: (payload: WebhookPayload) => Promise<void>
- onPaymentSucceeded?: (payload: WebhookPayload) => Promise<void>
- onPaymentFailed?: (payload: WebhookPayload) => Promise<void>
- onPaymentProcessing?: (payload: WebhookPayload) => Promise<void>
- onPaymentCancelled?: (payload: WebhookPayload) => Promise<void>
- onRefundSucceeded?: (payload: WebhookPayload) => Promise<void>
- onRefundFailed?: (payload: WebhookPayload) => Promise<void>
- onDisputeOpened?: (payload: WebhookPayload) => Promise<void>
- onDisputeExpired?: (payload: WebhookPayload) => Promise<void>
- onDisputeAccepted?: (payload: WebhookPayload) => Promise<void>
- onDisputeCancelled?: (payload: WebhookPayload) => Promise<void>
- onDisputeChallenged?: (payload: WebhookPayload) => Promise<void>
- onDisputeWon?: (payload: WebhookPayload) => Promise<void>
- onDisputeLost?: (payload: WebhookPayload) => Promise<void>
- onSubscriptionActive?: (payload: WebhookPayload) => Promise<void>
- onSubscriptionOnHold?: (payload: WebhookPayload) => Promise<void>
- onSubscriptionRenewed?: (payload: WebhookPayload) => Promise<void>
- onSubscriptionPlanChanged?: (payload: WebhookPayload) => Promise<void>
- onSubscriptionCancelled?: (payload: WebhookPayload) => Promise<void>
- onSubscriptionFailed?: (payload: WebhookPayload) => Promise<void>
- onSubscriptionExpired?: (payload: WebhookPayload) => Promise<void>
- onSubscriptionUpdated?: (payload: WebhookPayload) => Promise<void>
- onLicenseKeyCreated?: (payload: WebhookPayload) => Promise<void>
- onAbandonedCheckoutDetected?: (payload: WebhookPayload) => Promise<void>
- onAbandonedCheckoutRecovered?: (payload: WebhookPayload) => Promise<void>
- onDunningStarted?: (payload: WebhookPayload) => Promise<void>
- onDunningRecovered?: (payload: WebhookPayload) => Promise<void>
- onCreditAdded?: (payload: WebhookPayload) => Promise<void>
- onCreditDeducted?: (payload: WebhookPayload) => Promise<void>
- onCreditExpired?: (payload: WebhookPayload) => Promise<void>
- onCreditRolledOver?: (payload: WebhookPayload) => Promise<void>
- onCreditRolloverForfeited?: (payload: WebhookPayload) => Promise<void>
- onCreditOverageCharged?: (payload: WebhookPayload) => Promise<void>
- onCreditManualAdjustment?: (payload: WebhookPayload) => Promise<void>
- onCreditBalanceLow?: (payload: WebhookPayload) => Promise<void>

Environment Variable Setup:
To ensure the module functions correctly, set up the following environment variables in your Nuxt project's deployment environment (e.g., Vercel, Netlify, AWS, etc.):
- NUXT_PRIVATE_BEARER_TOKEN: Your Dodo Payments API Key (required for Checkout and Customer Portal).
- NUXT_PRIVATE_WEBHOOK_KEY: Your Dodo Payments Webhook Secret (required for Webhook handler).
- NUXT_PRIVATE_ENVIRONMENT: (Optional) Set to your environment (e.g., "test_mode" or "live_mode").
- NUXT_PRIVATE_RETURNURL: (Optional) The URL to redirect to after a successful checkout (for Checkout handler).

Usage in your code:
bearerToken: useRuntimeConfig().private.bearerToken
webhookKey: useRuntimeConfig().private.webhookKey

Important: Never commit sensitive environment variables directly into your version control. Use environment variables for all sensitive information.

If the user needs assistance setting up environment variables for their specific deployment environment, ask them what platform they are using (e.g., Vercel, Netlify, AWS, etc.), and provide guidance.