Overlay Checkout

Overlay checkout öppnar ett modalfönster ovanpå din sida. Kunder anger sina betalningsuppgifter i modalfönstret medan din sida förblir synlig bakom det. När de stänger modalfönstret återgår kontrollen till din sida. När de slutför betalningen omdirigeras de till return_url.

Overlay checkout-modal som visas ovanpå en produktsida

Interactive Demo

Se overlay checkout i praktiken med vår livedemo.

Snabbstart

Installera SDK:t, initiera det och öppna checkout med en checkout-URL från create checkout session API:

import { DodoPayments } from "dodopayments-checkout";

DodoPayments.Initialize({
  mode: "test",
  displayType: "overlay",
  onEvent: (event) => {
    console.log("Checkout event:", event);
  },
});

DodoPayments.Checkout.open({
  checkoutUrl: "https://test.checkout.dodopayments.com/session/cks_123"
});

Integration steg för steg

Install the SDK

Installera via npm, yarn eller pnpm:

npm install dodopayments-checkout

yarn add dodopayments-checkout

pnpm add dodopayments-checkout

Initialize the SDK

Anropa Initialize en gång när appen laddas, vanligtvis i din huvudkomponent eller appens startpunkt:

import { DodoPayments } from "dodopayments-checkout";

DodoPayments.Initialize({
  mode: "test", // Change to 'live' for production
  displayType: "overlay",
  onEvent: (event) => {
    console.log("Checkout event:", event);
    
    switch (event.event_type) {
      case "checkout.opened":
        // Modal has opened
        break;
      case "checkout.closed":
        // Modal has closed
        break;
      case "checkout.error":
        console.error("Checkout error:", event.data?.message);
        break;
    }
  },
});

Initiera alltid SDK:t innan du öppnar checkout. Initiera det en gång när applikationen laddas, inte före varje checkout-försök.

Create a Checkout Button

Skapa en komponent som öppnar checkout-modalen:

// components/CheckoutButton.tsx
"use client";

import { Button } from "@/components/ui/button";
import { DodoPayments } from "dodopayments-checkout";
import { useEffect, useState } from "react";

export function CheckoutButton() {
  const [isLoading, setIsLoading] = useState(false);

  useEffect(() => {
    DodoPayments.Initialize({
      mode: "test",
      displayType: "overlay",
      onEvent: (event) => {
        if (event.event_type === "checkout.opened") {
          setIsLoading(false);
        }
        if (event.event_type === "checkout.error") {
          setIsLoading(false);
          console.error("Checkout error:", event.data?.message);
        }
      },
    });
  }, []);

  const handleCheckout = async () => {
    setIsLoading(true);
    try {
      await DodoPayments.Checkout.open({
        checkoutUrl: "https://test.checkout.dodopayments.com/session/cks_123"
      });
    } catch (error) {
      console.error("Failed to open checkout:", error);
      setIsLoading(false);
    }
  };

  return (
    <Button 
      onClick={handleCheckout}
      disabled={isLoading}
    >
      {isLoading ? "Loading..." : "Checkout Now"}
    </Button>
  );
}

Add the Button to Your Page

Använd checkout-knappkomponenten i din applikation:

// app/page.tsx
import { CheckoutButton } from "@/components/CheckoutButton";

export default function Home() {
  return (
    <main className="flex min-h-screen flex-col items-center justify-center p-24">
      <h1>Welcome to Our Store</h1>
      <CheckoutButton />
    </main>
  );
}

Handle Redirects

Skapa sidor för att hantera checkout-omdirigeringar efter betalningen:

// app/success/page.tsx
export default function SuccessPage() {
  return (
    <div className="flex min-h-screen flex-col items-center justify-center">
      <h1>Payment Successful</h1>
      <p>Thank you for your purchase.</p>
    </div>
  );
}

// app/failure/page.tsx
export default function FailurePage() {
  return (
    <div className="flex min-h-screen flex-col items-center justify-center">
      <h1>Payment Failed</h1>
      <p>Please try again or contact support.</p>
    </div>
  );
}

Test Your Integration

Starta din utvecklingsserver:

npm run dev

Testa checkout-flödet:
- Klicka på checkout-knappen
- Kontrollera att modalen visas
- Testa betalningsflödet med testuppgifter
- Bekräfta att omdirigeringarna fungerar korrekt

Du bör se checkout-händelser loggas i webbläsarens konsol.

Go Live

När du är redo för produktion:

Ändra läget till 'live':

DodoPayments.Initialize({
  mode: "live",
  displayType: "overlay",
  onEvent: (event) => {
    console.log("Checkout event:", event);
  }
});

Uppdatera dina checkout-URL:er så att de använder live checkout-sessioner från din backend
Testa hela flödet i produktion
Övervaka händelser och fel

API-referens

Initiera

Anropa Initialize en gång för att konfigurera SDK:t:

interface InitializeOptions {
  mode: "test" | "live";
  displayType?: "overlay" | "inline";
  onEvent: (event: CheckoutEvent) => void;
}

DodoPayments.Initialize(options);

Alternativ	Typ	Obligatoriskt	Beskrivning
`mode`	`"test" \| "live"`	Ja	Miljöläge: `"test"` för utveckling, `"live"` för produktion
`displayType`	`"overlay" \| "inline"`	Nej	Visningstyp: `"overlay"` för modal checkout (standard), `"inline"` för inbäddad checkout
`onEvent`	`function`	Ja	Callback-funktion för hantering av checkout-händelser

Öppna checkout

Öppna checkout-modalen:

interface CheckoutOptions {
  checkoutUrl: string;
  options?: {
    showTimer?: boolean;
    showSecurityBadge?: boolean;
    manualRedirect?: boolean;
    themeConfig?: ThemeConfig;
    payButtonText?: string;
    fontSize?: FontSize;
    fontWeight?: FontWeight;
  };
}

DodoPayments.Checkout.open(options);

Alternativ	Typ	Obligatoriskt	Beskrivning
`checkoutUrl`	`string`	Ja	URL till checkout-sessionen från create checkout session API
`options.showTimer`	`boolean`	Nej	Visa eller dölj sessionstimern. Standardvärdet är `true`. När den är inaktiverad får du händelsen `checkout.link_expired` när sessionen löper ut.
`options.showSecurityBadge`	`boolean`	Nej	Visa eller dölj säkerhetsmärket. Standardvärdet är `true`
`options.manualRedirect`	`boolean`	Nej	När `true` förhindras automatiska omdirigeringar. Checkout skickar `checkout.status` med betalningsresultatet och `checkout.redirect_requested` med URL:en som ska öppnas, och du hanterar navigeringen
`options.themeConfig`	`ThemeConfig`	Nej	Föråldrat. Konfigurera temat på serversidan när du skapar checkout-sessionen i stället
`options.payButtonText`	`string`	Nej	Anpassad text för betalningsknappen
`options.fontSize`	`"xs" \| "sm" \| "md" \| "lg" \| "xl" \| "2xl"`	Nej	Global teckenstorlek för checkout
`options.fontWeight`	`"normal" \| "medium" \| "bold" \| "extraBold"`	Nej	Global teckenvikt för checkout

Stäng checkout

Stäng modalen programmatiskt:

DodoPayments.Checkout.close();

Kontrollera status

Kontrollera om modalen är öppen:

const isOpen = DodoPayments.Checkout.isOpen();
// Returns: boolean

Händelser

Lyssna på checkout-händelser via callbacken onEvent som skickas till Initialize:

DodoPayments.Initialize({
  onEvent: (event: CheckoutEvent) => {
    switch (event.event_type) {
      case "checkout.opened":
        // Modal has opened
        break;
      case "checkout.form_ready":
        // Form is ready for user input
        break;
      case "checkout.payment_page_opened":
        // Payment page is displayed
        break;
      case "checkout.customer_details_submitted":
        // Customer details submitted
        break;
      case "checkout.closed":
        // Modal has closed
        break;
      case "checkout.redirect":
        // Checkout will redirect
        break;
      case "checkout.error":
        console.error("Error:", event.data?.message);
        break;
      case "checkout.link_expired":
        // Session expired (only when showTimer is false)
        break;
    }
  }
});

Händelse	Beskrivning
`checkout.opened`	Modalen har öppnats
`checkout.form_ready`	Formuläret är klart för användarinmatning. Använd detta för att dölja laddningstillstånd
`checkout.payment_page_opened`	Betalningssidan visas
`checkout.customer_details_submitted`	Kund- och faktureringsuppgifter har skickats
`checkout.closed`	Modalen har stängts
`checkout.redirect`	Checkout kommer att omdirigera, till exempel till en banksida
`checkout.error`	Ett fel inträffade under checkout
`checkout.link_expired`	Checkout-sessionen löpte ut. Tas endast emot när `showTimer` har angetts till `false`.

CDN-implementation

För en snabb integration utan ett build-steg kan du läsa in SDK:t från CDN:

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <title>Dodo Payments Checkout</title>
  
  <script src="https://cdn.jsdelivr.net/npm/dodopayments-checkout@latest/dist/index.js"></script>
  <script>
    DodoPaymentsCheckout.DodoPayments.Initialize({
      mode: "test",
      displayType: "overlay",
      onEvent: (event) => {
        console.log('Checkout event:', event);
      }
    });
  </script>
</head>
<body>
  <button onclick="openCheckout()">Checkout Now</button>

  <script>
    function openCheckout() {
      DodoPaymentsCheckout.DodoPayments.Checkout.open({
        checkoutUrl: "https://test.checkout.dodopayments.com/session/cks_123"
      });
    }
  </script>
</body>
</html>

Temaanpassning

Alternativet themeConfig på klientsidan är föråldrat och kommer att tas bort i nästa huvudversion av Checkout SDK (v2.0.0). Om du skickar det loggas en varning om föråldrat API i webbläsarens konsol. Konfigurera i stället temat när du skapar checkout-sessionen via API:t med parametern customization.theme_config — se Checkout Theme Customization — eller visuellt på Design-sidan i dashboarden. Teman som konfigureras för sessionen gäller för overlay, inline och hosted checkout.

Det här avsnittet behandlar den föråldrade temakonfigurationen på klientsidan med Checkout SDK. Den rekommenderade metoden är att konfigurera teman på serversidan när du skapar en checkout-session via API:t med parametern theme_config. Se Checkout Theme Customization för konfiguration på API-nivå, eller använd Design-sidan i dashboarden för att konfigurera teman visuellt med liveförhandsgranskning.

Om du måste använda temakonfiguration på klientsidan skickar du themeConfig i parametern options:

DodoPayments.Checkout.open({
  checkoutUrl: "https://test.checkout.dodopayments.com/session/cks_123",
  options: {
    themeConfig: {
      light: {
        bgPrimary: "#FFFFFF",
        textPrimary: "#344054",
        buttonPrimary: "#A6E500",
      },
      dark: {
        bgPrimary: "#0D0D0D",
        textPrimary: "#FFFFFF",
        buttonPrimary: "#A6E500",
      },
      radius: "8px",
    },
  },
});

Temaparametrar

Alla tillgängliga temaparametrar för ljust och mörkt läge:

interface ThemeConfig {
  light?: {
    bgPrimary?: string;              // Primary background
    bgSecondary?: string;            // Secondary background (tabs, etc.)
    borderPrimary?: string;          // Primary border
    borderSecondary?: string;        // Secondary border
    textPrimary?: string;            // Primary text
    textSecondary?: string;          // Secondary text
    textPlaceholder?: string;        // Placeholder text
    textError?: string;              // Error text
    textSuccess?: string;            // Success text
    buttonPrimary?: string;          // Primary button background
    buttonPrimaryHover?: string;     // Primary button hover
    buttonTextPrimary?: string;      // Primary button text
    buttonSecondary?: string;        // Secondary button background
    buttonSecondaryHover?: string;   // Secondary button hover
    buttonTextSecondary?: string;    // Secondary button text
    inputFocusBorder?: string;       // Input focus border
  };
  dark?: {
    // Same properties as light mode
  };
  radius?: string;                   // Border radius (e.g., "8px")
}

Felhantering

Implementera alltid felhantering i din callback onEvent:

DodoPayments.Initialize({
  mode: "test",
  displayType: "overlay",
  onEvent: (event: CheckoutEvent) => {
    if (event.event_type === "checkout.error") {
      console.error("Checkout error:", event.data?.message);
      // Show user-friendly error message
      // Optionally retry the checkout
    }
    if (event.event_type === "checkout.link_expired") {
      console.warn("Checkout session has expired");
      // Create a new checkout session and try again
    }
  }
});

Hantera alltid händelsen checkout.error för att ge en bra användarupplevelse när fel uppstår.

Bästa praxis

Initiera en gång: Anropa Initialize en gång när appen laddas, inte före varje checkout
Felhantering: Implementera korrekt felhantering i din händelsecallback
Testläge: Använd läget "test" under utvecklingen och växla till "live" först när du är redo för produktion
Händelsehantering: Hantera alla relevanta händelser för en komplett användarupplevelse
Giltiga URL:er: Använd alltid giltiga checkout-URL:er från create checkout session API
TypeScript: Använd TypeScript för bättre typsäkerhet och utvecklarupplevelse
Laddningstillstånd: Visa laddningstillstånd medan checkout öppnas för att förbättra UX
Timerhantering: Inaktivera timern (showTimer: false) om du vill hantera sessionens utgång manuellt

Felsökning

Events not firing

Möjliga orsaker:

Händelsehanteraren har inte konfigurerats korrekt
JavaScript-fel hindrar händelsespridning
SDK:t har inte initierats korrekt

Lösningar:

Bekräfta att händelsehanteraren är korrekt konfigurerad i Initialize()
Kontrollera webbläsarens konsol efter JavaScript-fel
Kontrollera att SDK-initieringen slutfördes korrekt
Testa först med en enkel händelsehanterare

Styling issues

Möjliga orsaker:

CSS-konflikter med applikationens formatmallar
Temainställningarna har inte tillämpats korrekt
Problem med responsiv design

Lösningar:

Kontrollera om det finns CSS-konflikter i webbläsarens DevTools
Kontrollera att temainställningarna är korrekta
Testa på olika skärmstorlekar
Säkerställ att det inte finns några z-index-konflikter med modalen

Digitala plånböcker

Mer information om hur du konfigurerar Google Pay och andra digitala plånböcker finns på sidan Digital Wallets.

Apple Pay stöds ännu inte i overlay checkout.

Webbläsarstöd

Dodo Payments Checkout SDK stöder:

Chrome (senaste versionen)
Firefox (senaste versionen)
Safari (senaste versionen)
Edge (senaste versionen)
IE11+

Overlay kontra inline checkout

Välj rätt checkout-typ för ditt användningsfall:

Funktion	Overlay	Inline
Integrationsdjup	Modal ovanpå sidan	Helt inbäddad på sidan
Layoutkontroll	Begränsad	Full kontroll
Varumärkesprofilering	Separat från sidan	Matchar din sida
Implementeringsinsats	Mindre	Större
Bäst för	Snabb integration, befintliga sidor	Anpassade checkout-sidor, flöden med hög konvertering

Använd overlay checkout för snabbare integration med minimala ändringar på dina befintliga sidor. Använd inline checkout när du vill ha maximal kontroll över checkout-upplevelsen och konsekvent varumärkesprofilering.

Relaterade resurser

Inline Checkout

Bädda in checkout direkt på din sida för helt integrerade upplevelser.

Checkout Sessions API

Skapa checkout-sessioner för att driva dina checkout-upplevelser.

Webhooks

Hantera betalningshändelser på serversidan med webhooks.

Integration Guide

Komplett guide för integrering av Dodo Payments.

Besök vår Discord-community eller kontakta vårt supportteam för utvecklare om du behöver mer hjälp.

Getting Started

Features

Integrate

Merchant of Record

Miscellaneous

Interactive Demo

Snabbstart

Integration steg för steg

API-referens

Initiera

Öppna checkout

Stäng checkout

Kontrollera status

Händelser

CDN-implementation

Temaanpassning

Temaparametrar

Felhantering

Bästa praxis

Felsökning

Digitala plånböcker

Webbläsarstöd

Overlay kontra inline checkout

Relaterade resurser

Inline Checkout

Checkout Sessions API

Webhooks

Integration Guide

Interactive Demo

​Snabbstart

​Integration steg för steg

​API-referens

​Initiera

​Öppna checkout

​Stäng checkout

​Kontrollera status

​Händelser

​CDN-implementation

​Temaanpassning

​Temaparametrar

​Felhantering

​Bästa praxis

​Felsökning

​Digitala plånböcker

​Webbläsarstöd

​Overlay kontra inline checkout

​Relaterade resurser

Inline Checkout

Checkout Sessions API

Webhooks

Integration Guide

Snabbstart

Integration steg för steg

API-referens

Initiera

Öppna checkout

Stäng checkout

Kontrollera status

Händelser

CDN-implementation

Temaanpassning

Temaparametrar

Felhantering

Bästa praxis

Felsökning

Digitala plånböcker

Webbläsarstöd

Overlay kontra inline checkout

Relaterade resurser