Skip to main content

GitHub Repository

Källkod för FastAPI- och Dodo Payments-boilerplate.

Översikt

FastAPI-boilerplate är en Python-backend där Dodo Payments redan är anslutet. Den innehåller endpoints som skapar checkout-sessioner och Customer Portal-sessioner, en webhook-endpoint som verifierar signaturer samt en prissida som renderas från Jinja2-mallar.
Den här boilerplate-lösningen använder FastAPI med async-route handlers, Pydantic för validering och inställningar samt dodopayments Python SDK. Handlers anropar den synkrona klienten DodoPayments. För att undvika blockering av händelseslingan byter du till AsyncDodoPayments och await dess anrop.

Funktioner

Boilerplate-lösningen innehåller:
  • Snabb installation: Gå från kloning till en körande server på ungefär fem minuter.
  • Asynkrona handlers: Route handlers är FastAPI async def-funktioner.
  • Checkout-sessioner: En förkonfigurerad checkout-endpoint som använder Python SDK.
  • Webhook-hantering: En webhook-endpoint som verifierar varje signatur med SDK:ts unwrap-metod.
  • Customer Portal: En endpoint som skapar Customer Portal-sessioner.
  • Typsäkerhet: Pydantic-modeller validerar request bodies och koden använder type hints.
  • Miljökonfiguration: pydantic-settings läser in och validerar konfigurationen från .env.

Förutsättningar

Innan du börjar behöver du:
  • Python 3.9 eller senare, vilket krävs av dodopayments SDK. Python 3.11 eller senare rekommenderas.
  • pip eller uv för pakethantering.
  • Ett Dodo Payments-konto, för att skapa en API-nyckel och en webhook-signaturhemlighet i dashboarden.

Snabbstart

1

Clone the Repository

2

Create Virtual Environment

Konfigurera en isolerad Python-miljö:
Eller använd uv för snabbare beroendehantering:
3

Install Dependencies

Eller med uv:
4

Get API Credentials

Registrera dig på Dodo Payments och hämta sedan dina autentiseringsuppgifter från dashboarden:
Skapa båda medan reglaget Live Mode i sidofältet är avstängt. En testlägesnyckel fungerar endast med DODO_PAYMENTS_ENVIRONMENT=test_mode, och betalningar i testläge flyttar inga riktiga pengar.
5

Configure Environment Variables

Kopiera exempelfilen för att skapa en .env-fil i rotkatalogen:
Ange värdena för dina Dodo Payments-autentiseringsuppgifter:
.env
Alla fyra variabler krävs. app/core/config.py läser in dem med pydantic-settings, och appen startar inte om någon saknas eller är tom. DODO_PAYMENTS_RETURN_URL är den plats dit checkout skickar kunden efter betalningen.
Checka inte in din .env-fil i versionshanteringen. Repositoryts .gitignore exkluderar den redan.
6

Add Your Products

Ersätt exempelprodukterna i app/lib/products.py med dina egna. Ange varje product_id som ID:t för en produkt under Products i dashboarden. Prissidan visar dessa produkter.
7

Run the Development Server

Öppna http://localhost:8000/docs för att se den interaktiva API-dokumentationen.
Swagger UI listar endpoints /api/checkout/, /api/webhook/ och /api/customer-portal/, redo att testas.
Rot-URL:en, http://localhost:8000, visar prissidan.
app/main.py anropar templates.TemplateResponse("index.html", {"request": request, ...}), en signatur som Starlette 1.x inte längre accepterar, så prissidan returnerar ett 500-fel vid en nyinstallation. Ändra anropet till templates.TemplateResponse(request, "index.html", {"products": products}) för att åtgärda det.

Projektstruktur

API-endpoints

app/main.py monterar varje router under prefixet /api: Varje sökväg avslutas med ett snedstreck. FastAPI svarar på en begäran till sökvägen utan snedstrecket med en 307-omdirigering, så använd den exakta sökvägen, särskilt i din webhook-URL.

Kodexempel

Dessa exempel är förkortade versioner av filerna i app/api/.

Skapa en checkout-session

app/api/checkout.py skapar en checkout-session och returnerar dess checkout_url. Begärans body innehåller en product_id, en valfri quantity och ett valfritt customer-objekt med name och email:

Hantera webhooks

app/api/webhook.py verifierar signaturen med SDK:ts unwrap-metod och väljer sedan gren baserat på händelsetypen:

Integrering med Customer Portal

app/api/portal.py skapar en Customer Portal-session för ett kund-ID och returnerar portallänken som url:
Prissidan i app/templates/index.html skickar ett hårdkodat kund-ID (cus_001) till denna endpoint och ett hårdkodat namn och en hårdkodad e-postadress till checkout-endpointen. Ersätt dem med den inloggade användarens värden.

Webhook-händelser

Hanteraren i app/api/webhook.py väljer gren baserat på dessa händelser: Om du vill hantera en annan händelse lägger du till en gren för dess typ, till exempel refund.succeeded för en återbetalning som behandlades utan problem. Se guiden om webhook-händelser för alla händelsetyper. Lägg till din affärslogik i webhook-hanteraren för att:
  • Uppdatera användarbehörigheter i databasen
  • Skicka bekräftelsemeddelanden
  • Ge åtkomst till digitala produkter
  • Spåra analysdata och mätvärden

Testa webhooks lokalt

Dodo Payments kan inte nå localhost. Använd ett verktyg som ngrok för att exponera din lokala server vid lokal utveckling:
Lägg till ngrok-HTTPS-URL:en, följd av /api/webhook/, som en endpoint i din Dodo Payments Dashboard:
Kopiera endpointens signeringshemlighet till DODO_PAYMENTS_WEBHOOK_KEY i .env och starta sedan om servern. Appen läser .env endast vid uppstart.

Driftsättning

Docker

Förrådet innehåller ingen Dockerfile. Lägg till denna Dockerfile i förrådets rot för att köra appen i en container:
COPY . . kopierar varje fil i build context, inklusive .env. Lägg till en .dockerignore-fil som listar .env för att hålla dina nycklar utanför avbildningen. Bygg sedan avbildningen och kör den med din miljöfil:

Överväganden inför produktion

Innan du driftsätter till produktion:
  • Byt DODO_PAYMENTS_ENVIRONMENT till live_mode.
  • Använd en API-nyckel för liveläge från dashboarden.
  • Lägg till en webhook-endpoint för din produktionsdomän och ange DODO_PAYMENTS_WEBHOOK_KEY till dess signeringshemlighet.
  • Ange DODO_PAYMENTS_RETURN_URL till din produktions-URL.
  • Aktivera HTTPS för alla endpoints.

Felsökning

Kontrollera att din virtuella miljö är aktiverad och att beroenden är installerade:
app/main.py visar statiska filer från app/static, men förrådet innehåller inte den katalogen. Skapa den med mkdir app/static och starta sedan servern igen.
Kontrollera följande vanliga orsaker:
  • Produkt-ID:t finns inte i din Dodo Payments-dashboard.
  • API-nyckeln eller DODO_PAYMENTS_ENVIRONMENT i .env är felaktig. En nyckel för testläge fungerar endast med test_mode.
Endpointen returnerar SDK-felet i ett 400-svar. Kontrollera FastAPI-loggarna för detaljerade felmeddelanden.
Använd ngrok för att exponera din server vid lokal testning:
Lägg till en endpoint med ngrok-URL:en följd av /api/webhook/, inklusive det avslutande snedstrecket, i din Dodo-dashboard. Kopiera endpointens signeringshemlighet till DODO_PAYMENTS_WEBHOOK_KEY i din .env-fil.
  • Kontrollera att DODO_PAYMENTS_WEBHOOK_KEY i .env överensstämmer med endpointens signeringshemlighet.
  • Verifiera signaturen mot den råa request body:n innan du tolkar den som JSON.
  • Skicka alla tre headerna webhook-id, webhook-timestamp och webhook-signature till client.webhooks.unwrap(). Signaturen för Standard Webhooks omfattar id.timestamp.body, inte enbart bodyn.

Läs mer

Python SDK

Fullständig dokumentation för Python SDK med stöd för async

Webhooks Documentation

Läs mer om alla webhook-händelser och bästa praxis

Checkout Sessions

Fördjupad genomgång av konfigurationen för checkout-sessioner

API Reference

Fullständig dokumentation för Dodo Payments API

Support

Om du behöver hjälp med boilerplate-koden:
Senast ändrad 26 september 2026