Remix Adaptor

Aprenda como integrar os pagamentos Dodo com seu projeto Remix App Router usando nosso Remix Adaptor. Cobre checkout, portal do cliente, webhooks e configuração de ambiente seguro.

Checkout Handler

Integre o checkout da Dodo Payments ao seu app Remix.

Customer Portal

Permita que os clientes gerenciem assinaturas e detalhes.

Webhooks

Receba e processe eventos webhook da Dodo Payments.

​

Instalação

1. Install the package

   Execute o comando a seguir na raiz do seu projeto:

   npm install @dodopayments/remix
   
2. Set up environment variables

   Crie um .env na raiz do seu projeto:

   DODO_PAYMENTS_API_KEY=your-api-key
   DODO_PAYMENTS_WEBHOOK_SECRET=your-webhook-secret
   DODO_PAYMENTS_RETURN_URL=https://yourdomain.com/checkout/success
   DODO_PAYMENTS_ENVIRONMENT="test_mode" or "live_mode"
   

   Nunca comite seu .env ou segredos no controle de versão.

​

Exemplos de Manipuladores de Rota

Todos os exemplos assumem que você está usando o Remix App Router.

Checkout Handler

Use este handler para integrar o checkout da Dodo Payments ao seu app Remix. Suporta fluxos de pagamento estáticos (GET), dinâmicos (POST) e de sessão (POST).

Remix Route Handler

// app/routes/api.checkout.tsx
import { Checkout } from "@dodopayments/remix";
import type { LoaderFunctionArgs } from "@remix-run/node";

const checkoutGetHandler = Checkout({
    bearerToken: process.env.DODO_PAYMENTS_API_KEY,
    returnUrl: process.env.DODO_PAYMENTS_RETURN_URL,
    environment: process.env.DODO_PAYMENTS_ENVIRONMENT,
    type: "static"
});

const checkoutPostHandler = Checkout({
    bearerToken: process.env.DODO_PAYMENTS_API_KEY,
    returnUrl: process.env.DODO_PAYMENTS_RETURN_URL,
    environment: process.env.DODO_PAYMENTS_ENVIRONMENT,
    type: "dynamic", // for dynamic checkout
});

const checkoutSessionHandler = Checkout({
    bearerToken: process.env.DODO_PAYMENTS_API_KEY,
    returnUrl: process.env.DODO_PAYMENTS_RETURN_URL,
    environment: process.env.DODO_PAYMENTS_ENVIRONMENT,
    type: "session", // for checkout sessions
});

export const loader = ({ request }: LoaderFunctionArgs) => checkoutGetHandler(request);
export const action = ({ request }: LoaderFunctionArgs) => {
    // You can conditionally route to different handlers based on your needs
    // For checkout sessions, use checkoutSessionHandler(request)
    return checkoutPostHandler(request);
};

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 Handler

Use este handler para permitir que os clientes gerenciem suas assinaturas e detalhes por meio do portal do cliente da Dodo Payments.

Remix Route Handler

// app/routes/api.customer-portal.tsx
import { CustomerPortal } from "@dodopayments/remix";
import type { LoaderFunctionArgs } from "@remix-run/node";

const customerPortalHandler = CustomerPortal({
    bearerToken: process.env.DODO_PAYMENTS_API_KEY,
    environment: process.env.DODO_PAYMENTS_ENVIRONMENT
});

export const loader = ({ request }: LoaderFunctionArgs) => customerPortalHandler(request);

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 Handler

Use este handler para receber e processar eventos webhook da Dodo Payments de forma segura no seu app Remix.

Remix Route Handler

// app/routes/api.webhook.tsx
import { Webhooks } from "@dodopayments/remix";
import type { LoaderFunctionArgs } from "@remix-run/node";

const webhookHandler = Webhooks({
webhookKey: process.env.DODO_PAYMENTS_WEBHOOK_SECRET,
onPayload: async (payload) => {
    //Handle Payload Here
    console.log(payload)
}
});
export const action = ({ request }: LoaderFunctionArgs) => webhookHandler(request);

​

Manipulador de Rota de Checkout

O Dodo Payments oferece três tipos de fluxos de pagamento para integrar pagamentos ao seu site, e este adaptador oferece suporte a todos eles.

• Links de Pagamento Estáticos: URLs compartilháveis instantaneamente para coleta de pagamento rápida e sem código.
• Links de Pagamento Dinâmicos: Gere programaticamente links de pagamento 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 pré-configurados e detalhes do cliente.

Static Checkout (GET)

​

Parâmetros de Consulta

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 email 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

Desabilitar campo de nome completo.

disableFirstName · boolean

Desabilitar campo de primeiro nome.

disableLastName · boolean

Desabilitar campo de sobrenome.

disableEmail · boolean

Desabilitar campo de email.

disableCountry · boolean

Desabilitar campo de país.

disableAddressLine · boolean

Desabilitar campo de endereço.

disableCity · boolean

Desabilitar campo de cidade.

disableState · boolean

Desabilitar campo de estado.

disableZipCode · boolean

Desabilitar campo de CEP.

paymentCurrency · string

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

showCurrencySelector · boolean

Exibir seletor de moeda.

paymentAmount · integer

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

showDiscounts · boolean

Exibir campos de desconto.

metadata_* · string

Qualquer parâmetro de consulta que comece com metadata_ será enviado como metadados.

Se productId estiver ausente, o handler retorna uma resposta 400. Parâmetros de consulta inválidos também resultam em resposta 400.

​

Formato de 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 requisição POST.
• Suporta pagamentos únicos e recorrentes.
• Para uma lista completa de campos de corpo POST suportados, consulte:
  • Request body for a One Time Payment Product
  • Request body for a Subscription Product

​

Formato de 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 hospedado mais segura que lida com todo o fluxo de pagamento tanto para compras únicas quanto para assinaturas, com controle total de personalização.

Consulte o Guia de Integração de Sessões de Checkout para mais detalhes e uma lista completa de campos suportados.

​

Formato de 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 Portal do Cliente

O Manipulador de Rota do Portal do Cliente permite que você integre perfeitamente o portal do cliente dos pagamentos Dodo em sua aplicação Remix.

​

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 para o cliente com o link do portal.

Retorna 400 se customer_id estiver ausente.

​

Manipulador de Rota de Webhook

• Método: Apenas solicitações POST são suportadas. Outros métodos retornam 405.
• Verificação de Assinatura: Verifica a assinatura do webhook usando webhookKey. Retorna 401 se a verificação falhar.
• Validação de 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.

​

Handlers de Eventos Webhook Suportados

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 Remix developer assistant. Your task is to guide a user through integrating the @dodopayments/remix adapter into their existing Remix project.

The @dodopayments/remix adapter provides route handlers for Dodo Payments' Checkout, Customer Portal, and Webhook functionalities, designed for Remix route handlers.

First, install the necessary packages. Use the package manager appropriate for your project (npm, yarn, or bun) based on the presence of lock files (e.g., package-lock.json for npm, yarn.lock for yarn, bun.lockb for bun):

npm install @dodopayments/remix

Here's how you should structure your response:

    Ask the user which functionalities they want to integrate.

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

    Checkout Route Handler (for handling product checkouts)

    Customer Portal Route Handler (for managing customer subscriptions/details)

    Webhook Route Handler (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 Route Handler is selected:

Purpose: This handler redirects users to the Dodo Payments checkout page.
File Creation: Create a new file at app/routes/api.checkout.tsx in your Remix project.

Code Snippet:

// app/routes/api.checkout.tsx
import { Checkout } from "@dodopayments/remix";
import type { LoaderFunctionArgs } from "@remix-run/node";

const checkoutGetHandler = Checkout({
  bearerToken: process.env.DODO_PAYMENTS_API_KEY,
  returnUrl: process.env.DODO_PAYMENTS_RETURN_URL,
  environment: process.env.DODO_PAYMENTS_ENVIRONMENT,
  type: "static",
});

const checkoutPostHandler = Checkout({
  bearerToken: process.env.DODO_PAYMENTS_API_KEY,
  returnUrl: process.env.DODO_PAYMENTS_RETURN_URL,
  environment: process.env.DODO_PAYMENTS_ENVIRONMENT,
  type: "dynamic", // for dynamic checkout
});

const checkoutSessionHandler = Checkout({
  bearerToken: process.env.DODO_PAYMENTS_API_KEY,
  returnUrl: process.env.DODO_PAYMENTS_RETURN_URL,
  environment: process.env.DODO_PAYMENTS_ENVIRONMENT,
  type: "session", // for checkout sessions
});

export const loader = ({ request }: LoaderFunctionArgs) => checkoutGetHandler(request);

export const action = ({ request }: LoaderFunctionArgs) => {
  // You can conditionally route to different handlers based on your needs
  // For checkout sessions, use checkoutSessionHandler(request)
  return checkoutPostHandler(request);
};

If Customer Portal Route Handler is selected:

Purpose: This handler redirects authenticated users to their Dodo Payments customer portal.
File Creation: Create a new file at app/routes/api.customer-portal.tsx in your Remix project.

Code Snippet:

// app/routes/api.customer-portal.tsx
import { CustomerPortal } from "@dodopayments/remix";
import type { LoaderFunctionArgs } from "@remix-run/node";

const customerPortalHandler = CustomerPortal({
  bearerToken: process.env.DODO_PAYMENTS_API_KEY,
  environment: process.env.DODO_PAYMENTS_ENVIRONMENT
});

export const loader = ({ request }: LoaderFunctionArgs) => customerPortalHandler(request);

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 Route Handler is selected:

Purpose: This handler 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 app/routes/api.webhook.tsx in your Remix project.

Code Snippet:

// app/routes/api.webhook.tsx
import { Webhooks } from "@dodopayments/remix";
import type { LoaderFunctionArgs } from "@remix-run/node";

const webhookHandler = Webhooks({
  webhookKey: process.env.DODO_PAYMENTS_WEBHOOK_SECRET,
  onPayload: async (payload) => {
    //Handle Payload Here
    console.log(payload)
  }
});

export const action = ({ request }: LoaderFunctionArgs) => webhookHandler(request);

Handler Details:

    Method: Only POST requests are supported. Other methods return 405.

    Signature Verification: The handler verifies the webhook signature using the 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 Webhook Event Handlers:

    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 adapter functions correctly, you will need to manually set up the following environment variables in your Remix project's deployment environment (e.g., Vercel, Netlify, AWS, etc.):

    DODO_PAYMENTS_API_KEY: Your Dodo Payments API Key (required for Checkout and Customer Portal).

    DODO_PAYMENTS_RETURN_URL: (Optional) The URL to redirect to after a successful checkout (for Checkout handler).

    DODO_PAYMENTS_ENVIRONMENT: (Optional) The environment for the API (e.g., test or live).

    DODO_PAYMENTS_WEBHOOK_SECRET: Your Dodo Payments Webhook Secret (required for Webhook handler).

Example .env file:

DODO_PAYMENTS_API_KEY=your-api-key
DODO_PAYMENTS_RETURN_URL=your-return-url
DODO_PAYMENTS_ENVIRONMENT=test
DODO_PAYMENTS_WEBHOOK_SECRET=your-webhook-secret

Usage in your code:

bearerToken: process.env.DODO_PAYMENTS_API_KEY
webhookKey: process.env.DODO_PAYMENTS_WEBHOOK_SECRET

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. You can also add comments to their PR or chat depending on the context