Overlay Checkout - Dodo Payments Documentation

Översikt

Dodo Payments Checkout SDK erbjuder ett sömlöst sätt att integrera vår betalningsoverlay i din webbapplikation. Byggd med TypeScript och moderna webbstandarder, erbjuder den en robust lösning för att hantera betalningar med realtids-händelsehantering och anpassningsbara teman.

Demo

Interactive Demo

Se överläggskassan i aktion med vår live-demo.

Snabbstart

Kom igång med Dodo Payments Checkout SDK på bara några rader kod:

import { DodoPayments } from "dodopayments-checkout";

// Initialize the SDK
DodoPayments.Initialize({
  mode: "test", // 'test' or 'live'
  displayType: "overlay", // Optional: defaults to 'overlay' for overlay checkout
  onEvent: (event) => {
    console.log("Checkout event:", event);
  },
});

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

Hämta din checkout-URL från create checkout session API.

Steg-för-steg Integrationsguide

Install the SDK

Installera Dodo Payments Checkout SDK med din föredragna paketförvaltare:

npm install dodopayments-checkout

yarn add dodopayments-checkout

pnpm add dodopayments-checkout

Initialize the SDK

Initiera SDK:n i din applikation, vanligtvis i din huvudkomponent eller appens ingångspunkt:

import { DodoPayments } from "dodopayments-checkout";

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

Initiera alltid SDK:n innan du försöker öppna kassan. Initiering ska ske en gång när din applikation laddas.

Create a Checkout Button Component

Skapa en komponent som öppnar checkout-overlayen:

// 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(() => {
    // Initialize the SDK
    DodoPayments.Initialize({
      mode: "test",
      displayType: "overlay",
      onEvent: (event) => {
        switch (event.event_type) {
          case "checkout.opened":
            setIsLoading(false);
            break;
          case "checkout.error":
            setIsLoading(false);
            console.error("Checkout error:", event.data?.message);
            break;
        }
      },
    });
  }, []);

  const handleCheckout = async () => {
    try {
      setIsLoading(true);
      await DodoPayments.Checkout.open({
        checkoutUrl: "https://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 Checkout to Your Page

Använd checkout-knappskomponenten 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 Success and Failure Pages

Skapa sidor för att hantera checkout-omdirigeringar:

// 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
- Verifiera att overlayen visas
- Testa betalningsflödet med testuppgifter
- Bekräfta att omdirigeringar fungerar korrekt

Du bör se kassahändelser loggas i din webbläsares 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 för att använda live checkout-sessioner från din backend
Testa hela flödet i produktion
Övervaka händelser och fel

API Referens

Konfiguration

Initieringsalternativ

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

Alternativ	Typ	Obligatorisk	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 kassa (standard), `'inline'` för inbäddad kassa
`onEvent`	`function`	Ja	Callback-funktion för att hantera kassahändelser

Checkout-alternativ

interface CheckoutOptions {
  checkoutUrl: string;
  options?: {
    showTimer?: boolean;
    showSecurityBadge?: boolean;
  };
}

Alternativ	Typ	Obligatorisk	Beskrivning
`checkoutUrl`	`string`	Ja	Kassa session URL från create checkout session API
`options.showTimer`	`boolean`	Nej	Visa eller dölj kassatimer. Standard är `true`. När inaktiverad, får du eventet `checkout.link_expired` när sessionen går ut.
`options.showSecurityBadge`	`boolean`	Nej	Visa eller dölj säkerhetsmärket. Standard är `true`.

Metoder

Öppna Checkout

Öppnar checkout-overlayen med den angivna checkout-session-URL:en.

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

Du kan också skicka ytterligare alternativ för att anpassa checkout-beteendet:

DodoPayments.Checkout.open({
  checkoutUrl: "https://checkout.dodopayments.com/session/cks_123",
  options: {
    showTimer: false,
    showSecurityBadge: false,
  },
});

Stäng Kassa

Stänger programatiskt kassaöverlägget.

DodoPayments.Checkout.close();

Kontrollera Status

Returnerar om kassaöverlägget för närvarande är öppet.

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

Händelser

SDK:et tillhandahåller realtids händelser som du kan lyssna på genom callbacken onEvent:

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

Händelsetyp	Beskrivning
`checkout.opened`	Kassaöverlägget har öppnats
`checkout.form_ready`	Kassans formulär är redo att ta emot användarinmatning. Användbart för att dölja laddningstillstånd.
`checkout.payment_page_opened`	Betalningssidan har visats
`checkout.customer_details_submitted`	Kund- och faktureringsdetaljer har skickats in
`checkout.closed`	Kassaöverlägget har stängts
`checkout.redirect`	Kassa kommer att utföra en omdirigering
`checkout.error`	Ett fel inträffade under kassan
`checkout.link_expired`	Aktiveras när kassa sessionen går ut. Endast mottaget när `showTimer` är inställd på `false`.

Implementeringsalternativ

Installation via Paket Manager

Installera via npm, yarn eller pnpm enligt Steg-för-Steg Integrationsguiden.

CDN-Implementation

För snabb integration utan byggsteg kan du använda vår 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>
    
    <!-- Load DodoPayments -->
    <script src="https://cdn.jsdelivr.net/npm/dodopayments-checkout@latest/dist/index.js"></script>
    <script>
        // Initialize the SDK
        DodoPaymentsCheckout.DodoPayments.Initialize({
            mode: "test", // Change to 'live' for production
            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://checkout.dodopayments.com/session/cks_123"
            });
        }
    </script>
</body>
</html>

Temaanpassning

Du kan anpassa kassaens utseende genom att föra vidare ett objekt themeConfig i parametern options när kassan öppnas. Temakonfigurationen stöder både ljusa och mörka lägen, vilket tillåter dig att anpassa färger, kanter, text, knappar och kantbredder.

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åldrad funktionalitet i webbläsarens konsol. Konfigurera i stället ditt tema när du skapar checkout-sessionen via API:t genom att använda parametern customization.theme_config — se Anpassning av Checkout-tema — eller visuellt på sidan Design 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. Rekommenderat tillvägagångssätt är att konfigurera teman på serversidan när du skapar en checkout-session via API:t med parametern theme_config. Se Anpassning av Checkout-tema för konfiguration på API-nivå, eller använd sidan Design i dashboarden för att konfigurera teman visuellt med liveförhandsgranskning.

Grundläggande temakonfiguration

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

Fullständig temakonfiguration

Alla tillgängliga temaparametrar:

DodoPayments.Checkout.open({
  checkoutUrl: "https://checkout.dodopayments.com/session/cks_123",
  options: {
    themeConfig: {
      light: {
        // Background colors
        bgPrimary: "#FFFFFF",        // Primary background color
        bgSecondary: "#F9FAFB",      // Secondary background color (e.g., tabs)
        
        // Border colors
        borderPrimary: "#D0D5DD",     // Primary border color
        borderSecondary: "#6B7280",  // Secondary border color
        
        // Text colors
        textPrimary: "#344054",       // Primary text color
        textSecondary: "#6B7280",    // Secondary text color
        textPlaceholder: "#667085",  // Placeholder text color
        textError: "#D92D20",        // Error text color
        textSuccess: "#10B981",      // Success text color
        
        // Button colors
        buttonPrimary: "#A6E500",           // Primary button background
        buttonPrimaryHover: "#8CC500",      // Primary button hover state
        buttonTextPrimary: "#0D0D0D",       // Primary button text color
        buttonSecondary: "#F3F4F6",         // Secondary button background
        buttonSecondaryHover: "#E5E7EB",     // Secondary button hover state
        buttonTextSecondary: "#344054",     // Secondary button text color
      },
      dark: {
        // Background colors
        bgPrimary: "#0D0D0D",
        bgSecondary: "#1A1A1A",
        
        // Border colors
        borderPrimary: "#323232",
        borderSecondary: "#D1D5DB",
        
        // Text colors
        textPrimary: "#FFFFFF",
        textSecondary: "#909090",
        textPlaceholder: "#9CA3AF",
        textError: "#F97066",
        textSuccess: "#34D399",
        
        // Button colors
        buttonPrimary: "#A6E500",
        buttonPrimaryHover: "#8CC500",
        buttonTextPrimary: "#0D0D0D",
        buttonSecondary: "#2A2A2A",
        buttonSecondaryHover: "#3A3A3A",
        buttonTextSecondary: "#FFFFFF",
      },
      radius: "8px", // Border radius for inputs, buttons, and tabs
    },
  },
});

Endast ljust läge

Om du bara vill anpassa det ljusa temat:

DodoPayments.Checkout.open({
  checkoutUrl: "https://checkout.dodopayments.com/session/cks_123",
  options: {
    themeConfig: {
      light: {
        bgPrimary: "#FFFFFF",
        textPrimary: "#000000",
        buttonPrimary: "#0070F3",
      },
      radius: "12px",
    },
  },
});

Endast mörkt läge

Om du bara vill anpassa det mörka temat:

DodoPayments.Checkout.open({
  checkoutUrl: "https://checkout.dodopayments.com/session/cks_123",
  options: {
    themeConfig: {
      dark: {
        bgPrimary: "#000000",
        textPrimary: "#FFFFFF",
        buttonPrimary: "#0070F3",
      },
      radius: "12px",
    },
  },
});

Delvis åsidosättning av tema

Du kan åsidosätta endast specifika egenskaper. Checkout använder standardvärden för egenskaper som du inte anger:

DodoPayments.Checkout.open({
  checkoutUrl: "https://checkout.dodopayments.com/session/cks_123",
  options: {
    themeConfig: {
      light: {
        buttonPrimary: "#FF6B6B", // Only override primary button color
      },
      radius: "16px", // Override border radius
    },
  },
});

Temakonfiguration med andra alternativ

Du kan kombinera temakonfiguration med andra checkout-alternativ:

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

TypeScript-typer

För TypeScript-användare exporteras alla typer för temakonfiguration:

import { ThemeConfig, ThemeModeConfig } from "dodopayments-checkout";

const themeConfig: ThemeConfig = {
  light: {
    bgPrimary: "#FFFFFF",
    // ... other properties
  },
  dark: {
    bgPrimary: "#0D0D0D",
    // ... other properties
  },
  radius: "8px",
};

Felhantering

SDK:n tillhandahåller detaljerad felinformation via händelsesystemet. Implementera alltid korrekt 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);
      // Handle error appropriately
      // You may want to show a user-friendly error message
      // or retry the checkout process
    }
    if (event.event_type === "checkout.link_expired") {
      // Handle expired checkout session
      console.warn("Checkout session has expired");
    }
  }
});

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

Bästa praxis

Initiera en gång: Initiera SDK:n en gång när applikationen läses in, inte vid varje checkout-försök
Felhantering: Implementera alltid korrekt felhantering i din event callback
Testläge: Använd läget test under utvecklingen och byt 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 API:t för att skapa checkout-sessioner
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

Checkout not opening

Möjliga orsaker:

SDK:n har inte initierats innan open() anropades
Ogiltig checkout-URL
JavaScript-fel i konsolen
Problem med nätverksanslutningen

Lösningar:

Kontrollera att SDK:n initieras innan checkout öppnas
Kontrollera om det finns fel i konsolen
Säkerställ att checkout-URL:en är giltig och kommer från API:t för att skapa checkout-sessioner
Kontrollera nätverksanslutningen

Events not firing

Möjliga orsaker:

Event handler har inte konfigurerats korrekt
JavaScript-fel förhindrar händelsespridning
SDK:n har inte initierats korrekt

Lösningar:

Bekräfta att event handler ä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 event handler

Styling issues

Möjliga orsaker:

CSS-konflikter med applikationens stilar
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 inga z-index-konflikter finns med overlay

Aktivera digitala plånböcker

Detaljerad information om hur du konfigurerar Google Pay och andra digitala plånböcker finns på sidan Digitala plånböcker.

Apple Pay stöds ännu inte i overlay checkout. Stöd för Apple Pay kommer snart.

Webbläsarstöd

Dodo Payments Checkout SDK stöder följande webbläsare:

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 Checkout	Inline Checkout
Integrationsdjup	Modal ovanpå sidan	Helt inbäddad på sidan
Layoutkontroll	Begränsad	Full kontroll
Varumärkesprofilering	Separat från sidan	Sömlös
Implementeringsinsats	Lägre	Högre
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 en sömlös varumärkesprofilering.

Relaterade resurser

Inline Checkout

Bädda in checkout direkt på sidan 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 till integration med Dodo Payments.

Om du behöver mer hjälp kan du besöka vår Discord-community eller kontakta vårt supportteam för utvecklare.

​Översikt

​Demo

Interactive Demo

​Snabbstart

​Steg-för-steg Integrationsguide

​API Referens

​Konfiguration

​Initieringsalternativ

​Checkout-alternativ

​Metoder

​Öppna Checkout

​Stäng Kassa

​Kontrollera Status

​Händelser

​Implementeringsalternativ

​Installation via Paket Manager

​CDN-Implementation

​Temaanpassning

​Grundläggande temakonfiguration

​Fullständig temakonfiguration

​Endast ljust läge

​Endast mörkt läge

​Delvis åsidosättning av tema

​Temakonfiguration med andra alternativ

​TypeScript-typer

​Felhantering

​Bästa praxis

​Felsökning

​Aktivera digitala plånböcker

​Webbläsarstöd

​Overlay- kontra inline-checkout

​Relaterade resurser

Inline Checkout

Checkout Sessions API

Webhooks

Integration Guide

Översikt

Demo

Snabbstart

Steg-för-steg Integrationsguide

API Referens

Konfiguration

Initieringsalternativ

Checkout-alternativ

Metoder

Öppna Checkout

Stäng Kassa

Kontrollera Status

Händelser

Implementeringsalternativ

Installation via Paket Manager

CDN-Implementation

Temaanpassning

Grundläggande temakonfiguration

Fullständig temakonfiguration

Endast ljust läge

Endast mörkt läge

Delvis åsidosättning av tema

Temakonfiguration med andra alternativ

TypeScript-typer

Felhantering

Bästa praxis

Felsökning

Aktivera digitala plånböcker

Webbläsarstöd

Overlay- kontra inline-checkout

Relaterade resurser