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

Interaktiv Demo

Se overlay checkout 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"
});

Få din checkout-URL från create checkout session API.

Steg-för-steg Integrationsguide

Installera SDK:n

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

npm install dodopayments-checkout

Initiera SDK:n

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 checkout. Initiering bör ske en gång när din applikation laddas.

Skapa en Checkout-knappskomponent

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>
  );
}

Lägg till Checkout på din sida

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>
  );
}

Hantera framgångs- och misslyckandesidor

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>
  );
}

Testa din 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 checkout-händelser loggade i din webbläsares konsol.

Gå 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 checkout (standard), `'inline'` för inbäddad checkout
`onEvent`	`function`	Ja	Callback-funktion för att hantera checkout-händelser

Checkout-alternativ

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

Alternativ	Typ	Obligatorisk	Beskrivning
`checkoutUrl`	`string`	Ja	Checkout-sessionens URL från create checkout session API
`options.showTimer`	`boolean`	Nej	Visa eller dölja checkout-timern. Standard är `true`. När den är inaktiverad får du `checkout.link_expired`-händelsen när sessionen går ut.
`options.showSecurityBadge`	`boolean`	Nej	Visa eller dölja säkerhetsmärket. Standard är `true`.
`options.manualRedirect`	`boolean`	Nej	När den är aktiverad kommer checkout inte att omdirigera automatiskt efter slutförande. Istället får du `checkout.status` och `checkout.redirect_requested`-händelser för att hantera omdirigeringen själv.

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,
    manualRedirect: true,
  },
});

När du använder manualRedirect, hantera checkout-slutförandet i din onEvent callback:

DodoPayments.Initialize({
  mode: "test",
  displayType: "overlay",
  onEvent: (event) => {
    if (event.event_type === "checkout.status") {
      const status = event.data?.message?.status;
      // Handle status: "succeeded", "failed", or "processing"
    }
    if (event.event_type === "checkout.redirect_requested") {
      const redirectUrl = event.data?.message?.redirect_to;
      // Redirect the customer manually
      window.location.href = redirectUrl;
    }
    if (event.event_type === "checkout.link_expired") {
      // Handle expired checkout session
    }
  },
});

Stäng Checkout

Stänger programatiskt checkout-overlay.

DodoPayments.Checkout.close();

Kontrollera Status

Returnerar om checkout-overlay för närvarande är öppen.

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

Händelser

SDK:n tillhandahåller realtids-händelser som du kan lyssna på genom onEvent callback:

Checkout Status Händelsedata

När manualRedirect är aktiverad, får du checkout.status-händelsen med följande data:

interface CheckoutStatusEventData {
  message: {
    status?: "succeeded" | "failed" | "processing";
  };
}

Checkout Omdirigering Begärd Händelsedata

När manualRedirect är aktiverad, får du checkout.redirect_requested-händelsen med följande data:

interface CheckoutRedirectRequestedEventData {
  message: {
    redirect_to?: string;
  };
}

DodoPayments.Initialize({
  onEvent: (event: CheckoutEvent) => {
    switch (event.event_type) {
      case "checkout.opened":
        // Checkout overlay has been opened
        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;
      case "checkout.status":
        // Checkout status update (only when manualRedirect is enabled)
        const status = event.data?.message?.status;
        break;
      case "checkout.redirect_requested":
        // Redirect requested (only when manualRedirect is enabled)
        const redirectUrl = event.data?.message?.redirect_to;
        break;
    }
  }
});

Händelsetyp	Beskrivning
`checkout.opened`	Checkout-overlay har öppnats
`checkout.payment_page_opened`	Betalningssidan har visats
`checkout.customer_details_submitted`	Kund- och faktureringsuppgifter har skickats
`checkout.closed`	Checkout-overlay har stängts
`checkout.redirect`	Checkout kommer att utföra en omdirigering
`checkout.error`	Ett fel inträffade under checkout
`checkout.link_expired`	Utlöses när checkout-sessionen går ut. Endast mottagen när `showTimer` är inställt på `false`.
`checkout.status`	Utlöses när `manualRedirect` är aktiverad. Innehåller checkout-status (`succeeded`, `failed`, eller `processing`).
`checkout.redirect_requested`	Utlöses när `manualRedirect` är aktiverad. Innehåller URL:en för att omdirigera kunden till.

Implementeringsalternativ

Paketmanagerinstallation

Installera via npm, yarn eller pnpm som visas i Steg-för-steg integrationsguiden.

CDN-implementering

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 utseendet på kassan genom att skicka ett themeConfig objekt i options parametern när du öppnar kassan. Temakonfigurationen stöder både ljusa och mörka lägen, vilket gör att du kan anpassa färger, kanter, text, knappar och kantradie.

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",
    },
  },
});

Komplett temakonfiguration

Alla tillgängliga temaegenskaper:

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 ljus 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",
    },
  },
});

Partiell temaupphävning

Du kan endast åsidosätta specifika egenskaper. Kassan kommer att använda standardvärden för egenskaper som du inte specificerar:

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 kassaval:

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

TypeScript-typer

För TypeScript-användare exporteras alla temakonfigurationstyper:

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 genom händelsessystemet. Implementera alltid korrekt felhantering i din onEvent callback:

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 checkout.error händelsen för att ge en bra användarupplevelse när fel inträffar.

Bästa praxis

Initiera en gång: Initiera SDK:n en gång när din applikation laddas, inte vid varje kassa-försök
Felhantering: Implementera alltid korrekt felhantering i din händelsecallback
Testläge: Använd test läge under utveckling och väx 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 kassa-URL:er från API:t för att skapa kassa-sessioner
TypeScript: Använd TypeScript för bättre typ-säkerhet och utvecklarupplevelse
Laddningsstatusar: Visa laddningsstatusar medan kassan öppnas för att förbättra UX
Manuella omdirigeringar: Använd manualRedirect när du behöver anpassad kontroll över navigering efter kassan
Timerhantering: Inaktivera timern (showTimer: false) om du vill hantera sessionens utgång manuellt

Felsökning

Kassan öppnas inte

Möjliga orsaker:

SDK:n är inte initierad innan open() anropas
Ogiltig kassa-URL
JavaScript-fel i konsolen
Nätverksanslutningsproblem

Lösningar:

Verifiera att SDK-initieringen sker innan kassan öppnas
Kontrollera konsolen för fel
Se till att kassa-URL:en är giltig och kommer från API:t för att skapa kassa-sessioner
Verifiera nätverksanslutningen

Händelser utlöses inte

Möjliga orsaker:

Händelsehanteraren är inte korrekt inställd
JavaScript-fel förhindrar händelsepropagering
SDK:n är inte korrekt initierad

Lösningar:

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

Stilproblem

Möjliga orsaker:

CSS-konflikter med dina applikationsstilar
Temainställningar tillämpas inte korrekt
Responsiv designproblem

Lösningar:

Kontrollera för CSS-konflikter i webbläsarens DevTools
Verifiera att temainställningarna är korrekta
Testa på olika skärmstorlekar
Se till att det inte finns några z-index-konflikter med överlägg

Aktivera Apple Pay

Apple Pay gör det möjligt för kunder att slutföra betalningar snabbt och säkert med sina sparade betalningsmetoder. När det är aktiverat kan kunder starta Apple Pay-modalen direkt från kassaöverlägget på stödda enheter.

Apple Pay stöds på iOS 17+, iPadOS 17+ och Safari 17+ på macOS.

För att aktivera Apple Pay för din domän i produktion, följ dessa steg:

Ladda ner och ladda upp Apple Pay domänassocieringsfilen

Ladda ner Apple Pay domänassocieringsfilen.Ladda upp filen till din webbserver på /.well-known/apple-developer-merchantid-domain-association. Till exempel, om din webbplats är example.com, gör filen tillgänglig på https://example.com/well-known/apple-developer-merchantid-domain-association.

Begär aktivering av Apple Pay

E-posta [email protected] med följande information:

Din produktionsdomän-URL (t.ex. https://example.com)
Begäran om att aktivera Apple Pay för din domän

Du kommer att få bekräftelse inom 1-2 arbetsdagar när Apple Pay har aktiverats för din domän.

Verifiera tillgänglighet för Apple Pay

Efter att ha fått bekräftelse, testa Apple Pay i din kassa:

Öppna din kassa på en stödd enhet (iOS 17+, iPadOS 17+ eller Safari 17+ på macOS)
Verifiera att Apple Pay-knappen visas som ett betalningsalternativ
Testa hela betalningsflödet

Apple Pay måste aktiveras för din domän innan det visas som ett betalningsalternativ i produktion. Kontakta supporten innan du går live om du planerar att erbjuda Apple Pay.

Webbläsarstöd

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

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

Överlägg vs Inline-kassa

Välj rätt kassatyp för ditt användningsfall:

Funktion	Överläggskassa	Inline-kassa
Integrationsdjup	Modal ovanpå sidan	Helt inbäddad i sidan
Layoutkontroll	Begränsad	Full kontroll
Branding	Separat från sidan	Sömlös
Implementeringsinsats	Lägre	Högre
Bäst för	Snabb integration, befintliga sidor	Anpassade kassasidor, högkonverterande flöden

Använd överläggskassa för snabbare integration med minimala förändringar i dina befintliga sidor. Använd inline-kassa när du vill ha maximal kontroll över kassaupplevelsen och sömlös branding.

Relaterade resurser

Inline-kassa

Bädda in kassan direkt i din sida för helt integrerade upplevelser.

Kassa-sessioner API

Skapa kassa-sessioner för att driva dina kassaupplevelser.

Webhooks

Hantera betalningsevenemang server-side med webhooks.

Integrationsguide

Komplett guide för att integrera Dodo Payments.

För mer hjälp, besök vår Discord-community eller kontakta vårt utvecklarstöd.

Getting Started

Features

Integrate

Merchant of Record

Miscellaneous

​Översikt

​Demo

Interaktiv Demo

​Snabbstart

​Steg-för-steg Integrationsguide

​API Referens

​Konfiguration

​Initieringsalternativ

​Checkout-alternativ

​Metoder

​Öppna Checkout

​Stäng Checkout

​Kontrollera Status

​Händelser

​Checkout Status Händelsedata

​Checkout Omdirigering Begärd Händelsedata

​Implementeringsalternativ

​Paketmanagerinstallation

​CDN-implementering

​Temaanpassning

​Grundläggande temakonfiguration

​Komplett temakonfiguration

​Endast ljus läge

​Endast mörkt läge

​Partiell temaupphävning

​Temakonfiguration med andra alternativ

​TypeScript-typer

​Felhantering

​Bästa praxis

​Felsökning

​Aktivera Apple Pay

​Webbläsarstöd

​Överlägg vs Inline-kassa

​Relaterade resurser

Inline-kassa

Kassa-sessioner API

Webhooks

Integrationsguide

Översikt

Demo

Snabbstart

Steg-för-steg Integrationsguide

API Referens

Konfiguration

Initieringsalternativ

Checkout-alternativ

Metoder

Öppna Checkout

Stäng Checkout

Kontrollera Status

Händelser

Checkout Status Händelsedata

Checkout Omdirigering Begärd Händelsedata

Implementeringsalternativ

Paketmanagerinstallation

CDN-implementering

Temaanpassning

Grundläggande temakonfiguration

Komplett temakonfiguration

Endast ljus läge

Endast mörkt läge

Partiell temaupphävning

Temakonfiguration med andra alternativ

TypeScript-typer

Felhantering

Bästa praxis

Felsökning

Aktivera Apple Pay

Webbläsarstöd

Överlägg vs Inline-kassa

Relaterade resurser