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-settingslä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
dodopaymentsSDK. 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
4
Get API Credentials
Registrera dig på Dodo Payments och hämta sedan dina autentiseringsuppgifter från dashboarden:
- API-nyckel: Skapa en nyckel under Dashboard → Developer → API Keys.
- Webhook-nyckel: Lägg till en endpoint under Dashboard → Developer → Webhooks och kopiera sedan dess signaturhemlighet. Endpoint-URL:en måste vara offentlig och använda HTTPS. Om du vill ta emot händelser på din dator kan du läsa Testa webhooks lokalt.
5
Configure Environment Variables
Kopiera exempelfilen för att skapa en Ange värdena för dina Dodo Payments-autentiseringsuppgifter:Alla fyra variabler krävs.
.env-fil i rotkatalogen:.env
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.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
Swagger UI listar endpoints
/api/checkout/, /api/webhook/ och /api/customer-portal/, redo att testas.http://localhost:8000, visar prissidan.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 iapp/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:
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 iapp/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:
/api/webhook/, som en endpoint i din Dodo Payments Dashboard:
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 ingenDockerfile. 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
Felsökning
Import errors or missing modules
Import errors or missing modules
Kontrollera att din virtuella miljö är aktiverad och att beroenden är installerade:
Server fails to start with Directory 'app/static' does not exist
Server fails to start with Directory 'app/static' does not exist
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.Checkout session creation fails
Checkout session creation fails
Kontrollera följande vanliga orsaker:
- Produkt-ID:t finns inte i din Dodo Payments-dashboard.
- API-nyckeln eller
DODO_PAYMENTS_ENVIRONMENTi.envär felaktig. En nyckel för testläge fungerar endast medtest_mode.
400-svar. Kontrollera FastAPI-loggarna för detaljerade felmeddelanden.Webhooks not receiving events
Webhooks not receiving events
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.Webhook signature verification fails
Webhook signature verification fails
- Kontrollera att
DODO_PAYMENTS_WEBHOOK_KEYi.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-timestampochwebhook-signaturetillclient.webhooks.unwrap(). Signaturen för Standard Webhooks omfattarid.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:- Ställ frågor i Discord-communityn.
- Rapportera problem och följ uppdateringar i GitHub-förrådet.
- Mejla supportteamet.