Mobilintegrationsguide

​

Förutsättningar

• Ett Dodo Payments-konto.
• En API-nyckel från Developer → API Keys och en webhook-signaturhemlighet från Developer → Webhooks.
• En Android-, iOS-, React Native- eller Flutter-app.
• En backend-server som skapar checkout-sessioner. API-nyckeln ska finnas kvar på denna server.

​

Integrationsflöde

func getCheckoutURL(productId: String, customerEmail: String, customerName: String) async throws -> String {
    let url = URL(string: "https://your-backend.com/api/create-checkout-session")!
    var request = URLRequest(url: url)
    request.httpMethod = "POST"
    request.setValue("application/json", forHTTPHeaderField: "Content-Type")
    request.setValue("Bearer \(userSessionToken)", forHTTPHeaderField: "Authorization")
    
    let requestData: [String: Any] = [
        "productId": productId,
        "customerEmail": customerEmail,
        "customerName": customerName
    ]
    request.httpBody = try JSONSerialization.data(withJSONObject: requestData)
    
    let (data, _) = try await URLSession.shared.data(for: request)
    let response = try JSONDecoder().decode(CheckoutResponse.self, from: data)
    return response.checkout_url
}

suspend fun getCheckoutURL(productId: String, customerEmail: String, customerName: String): String {
    val client = OkHttpClient()
    val requestBody = JSONObject().apply {
        put("productId", productId)
        put("customerEmail", customerEmail)
        put("customerName", customerName)
    }.toString().toRequestBody("application/json".toMediaType())
    
    val request = Request.Builder()
        .url("https://your-backend.com/api/create-checkout-session")
        .header("Authorization", "Bearer $userSessionToken")
        .post(requestBody)
        .build()
    
    val response = client.newCall(request).execute()
    val responseBody = response.body?.string()
    val jsonResponse = JSONObject(responseBody ?: "")
    return jsonResponse.getString("checkout_url")
}

const getCheckoutURL = async (productId, customerEmail, customerName) => {
  try {
    const response = await fetch('https://your-backend.com/api/create-checkout-session', {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        'Authorization': `Bearer ${userSessionToken}`,
      },
      body: JSON.stringify({
        productId,
        customerEmail,
        customerName
      })
    });
    
    const data = await response.json();
    return data.checkout_url;
  } catch (error) {
    console.error('Failed to get checkout URL:', error);
    throw error;
  }
};

import 'dart:convert';
import 'package:http/http.dart' as http;

Future<String> getCheckoutUrl({
  required String productId,
  required String customerEmail,
  required String customerName,
}) async {
  final response = await http.post(
    Uri.parse('https://your-backend.com/api/create-checkout-session'),
    headers: {
      'Content-Type': 'application/json',
      'Authorization': 'Bearer $userSessionToken',
    },
    body: jsonEncode({
      'productId': productId,
      'customerEmail': customerEmail,
      'customerName': customerName,
    }),
  );

  if (response.statusCode != 200) {
    throw Exception('Failed to get checkout URL: ${response.statusCode}');
  }
  return jsonDecode(response.body)['checkout_url'] as String;
}

​

Välj ditt SDK

​

Registrera ett callback-URL-schema

android {
    defaultConfig {
        manifestPlaceholders["dodoCallbackScheme"] = "myapp"
    }
}

<key>CFBundleURLTypes</key>
<array>
  <dict>
    <key>CFBundleURLName</key>
    <string>myapp</string>
    <key>CFBundleURLSchemes</key>
    <array>
      <string>myapp</string>
    </array>
  </dict>
</array>

{
  "expo": {
    "scheme": "myapp",
    "plugins": [
      [
        "@dodopayments/react-native-checkout",
        { "scheme": "myappcheckout" }
      ]
    ]
  }
}

​

Anpassa utseendet

const result = await DodoCheckout.start({
  checkoutUrl,
  returnUrl: 'myapp://checkout/return',
  customization: {
    android: { toolbarColor: '#6366F1', closeButtonStyle: 'back' },
    ios: { presentationStyle: 'fullScreen', colorScheme: 'dark' },
  },
});

final result = await DodoCheckout.instance.start(
  CheckoutParams(
    checkoutUrl: Uri.parse(checkoutUrl),
    returnUrl: Uri.parse('myapp://checkout/return'),
    customization: BrowserCustomization(
      android: AndroidBrowserOptions(
        toolbarColor: Color(0xFF6366F1),
        closeButtonStyle: CloseButtonStyle.back,
      ),
      ios: IosBrowserOptions(
        presentationStyle: PresentationStyle.fullScreen,
        colorScheme: BrowserColorScheme.dark,
      ),
    ),
  ),
);

val result = DodoCheckout.start(
    activity,
    CheckoutParams(
        checkoutUrl = checkoutUrl,
        returnUrl = "myapp://checkout/return",
        customization = BrowserCustomization(
            toolbarColor = Color.parseColor("#6366F1"),
            closeButtonStyle = BrowserCustomization.CloseButtonStyle.BACK,
        )
    )
) { event -> }

let result = try await DodoCheckout.start(
    checkoutUrl: checkoutUrl,
    returnUrl: URL(string: "myapp://checkout/return")!,
    customization: BrowserCustomization(
        presentationStyle: .fullScreen,
        colorScheme: .dark
    )
)

​

Anpassa checkout-sidan

​

Mobiloptimerade recept

Minimal Mobile Checkout - fastest path to payment

Använd detta recept för det kortaste formuläret: betalningsmetoder högst upp, endast postnummer för adressen, inget rabattkodsfält och ett tema som följer enheten.

• Node.js SDK
• Python SDK

import DodoPayments from 'dodopayments';

const client = new DodoPayments({
  bearerToken: process.env.DODO_PAYMENTS_API_KEY,
  environment: 'test_mode',
});

const session = await client.checkoutSessions.create({
  product_cart: [{ product_id: 'pdt_your_product_id', quantity: 1 }],
  customer: { email: 'user@example.com', name: 'Jane Smith' },
  billing_address: { country: 'US' },
  return_url: 'myapp://checkout/success',
  cancel_url: 'myapp://checkout/cancelled',
  billing_currency: 'USD',
  minimal_address: true,
  customization: {
    show_order_details: false,
    theme: 'system',
  },
  feature_flags: {
    allow_discount_code: false,
    allow_currency_selection: false,
  },
});

console.log(session.checkout_url);

See all 26 lines

import os
import dodopayments

client = dodopayments.DodoPayments(
    bearer_token=os.environ.get("DODO_PAYMENTS_API_KEY"),
    environment="test_mode",
)

session = client.checkout_sessions.create(
    product_cart=[{"product_id": "pdt_your_product_id", "quantity": 1}],
    customer={"email": "user@example.com", "name": "Jane Smith"},
    billing_address={"country": "US"},
    return_url="myapp://checkout/success",
    cancel_url="myapp://checkout/cancelled",
    billing_currency="USD",
    minimal_address=True,
    customization={
        "show_order_details": False,
        "theme": "system",
    },
    feature_flags={
        "allow_discount_code": False,
        "allow_currency_selection": False,
    },
)

print(session.checkout_url)

See all 27 lines

Se Checkout Sessions för alla tillgängliga parametrar och deras standardvärden.

Branded Mobile Checkout - custom colors, fonts, and button label

Använd detta recept när checkout-sidan måste se ut som en del av appen. Det anger dina varumärkesfärger, en hörnradie och en anpassad etikett på betalningsknappen.

• Node.js SDK
• Python SDK

const session = await client.checkoutSessions.create({
  product_cart: [{ product_id: 'pdt_your_product_id', quantity: 1 }],
  customer: { email: 'user@example.com', name: 'Jane Smith' },
  billing_address: { country: 'US' },
  billing_currency: 'USD',
  return_url: 'myapp://checkout/success',
  minimal_address: true,
  customization: {
    show_order_details: false,
    theme: 'dark',
    theme_config: {
      dark: {
        button_primary: '#7C3AED',
        button_primary_hover: '#6D28D9',
        button_text_primary: '#FFFFFF',
        bg_primary: '#1A1A2E',
        bg_secondary: '#16213E',
        text_primary: '#E2E8F0',
      },
      pay_button_text: 'Complete Purchase',
      radius: '8px',
    },
  },
});

See all 24 lines

session = client.checkout_sessions.create(
    product_cart=[{"product_id": "pdt_your_product_id", "quantity": 1}],
    customer={"email": "user@example.com", "name": "Jane Smith"},
    billing_address={"country": "US"},
    billing_currency="USD",
    return_url="myapp://checkout/success",
    minimal_address=True,
    customization={
        "show_order_details": False,
        "theme": "dark",
        "theme_config": {
            "dark": {
                "button_primary": "#7C3AED",
                "button_primary_hover": "#6D28D9",
                "button_text_primary": "#FFFFFF",
                "bg_primary": "#1A1A2E",
                "bg_secondary": "#16213E",
                "text_primary": "#E2E8F0",
            },
            "pay_button_text": "Complete Purchase",
            "radius": "8px",
        },
    },
)

See all 24 lines

theme_config accepterar separata objekt för dark och light, så att färgpaletten följer enhetens utseende. Information om varje färgnyckel och typsnittsalternativet finns i Checkout Sessions.

One-Click Returning Customer - saved card, instant confirmation

Använd detta recept för inloggade kunder som har betalat tidigare. Skicka kundens customer_id, deras sparade payment_method_id och confirm: true för att hoppa över checkout-formuläret. Med en payment_method_id debiterar sessionen den sparade metoden direkt och returnerar ingen checkout_url, så appen har inget att öppna. Ta reda på resultatet via webhooks.

• Node.js SDK
• Python SDK

const session = await client.checkoutSessions.create({
  product_cart: [{ product_id: 'pdt_your_product_id', quantity: 1 }],
  customer: { customer_id: 'cus_returning_customer_id' },
  // confirm: true requires a complete billing address
  billing_address: {
    country: 'US',
    state: 'CA',
    city: 'San Francisco',
    street: '123 Main St',
    zipcode: '94102',
  },
  billing_currency: 'USD',
  return_url: 'myapp://checkout/success',
  payment_method_id: 'pm_saved_payment_method_id',
  confirm: true,
  show_saved_payment_methods: true,           // top-level parameter
  feature_flags: { redirect_immediately: true },
});

See all 18 lines

session = client.checkout_sessions.create(
    product_cart=[{"product_id": "pdt_your_product_id", "quantity": 1}],
    customer={"customer_id": "cus_returning_customer_id"},
    # confirm=True requires a complete billing address
    billing_address={
        "country": "US",
        "state": "CA",
        "city": "San Francisco",
        "street": "123 Main St",
        "zipcode": "94102",
    },
    billing_currency="USD",
    return_url="myapp://checkout/success",
    payment_method_id="pm_saved_payment_method_id",
    confirm=True,
    show_saved_payment_methods=True,           # top-level parameter
    feature_flags={"redirect_immediately": True},
)

See all 18 lines

Bevilja åtkomst när din backend tar emot payment.succeeded-webhooken. Alla status som appen visar är endast UI-indikeringar.

Subscription with Free Trial - trial before first charge

Använd detta recept för en prenumerationsprodukt med en kostnadsfri provperiod före den första debiteringen. trial_period_days anger provperiodens längd för denna session.

• Node.js SDK
• Python SDK

const session = await client.checkoutSessions.create({
  product_cart: [{ product_id: 'pdt_your_subscription_product_id', quantity: 1 }],
  customer: { email: 'user@example.com', name: 'Jane Smith' },
  billing_address: { country: 'US' },
  billing_currency: 'USD',
  return_url: 'myapp://subscription/activated',
  cancel_url: 'myapp://subscription/cancelled',
  minimal_address: true,
  customization: {
    show_order_details: false,
    theme: 'system',
  },
  subscription_data: { trial_period_days: 14 },
});

See all 14 lines

session = client.checkout_sessions.create(
    product_cart=[{"product_id": "pdt_your_subscription_product_id", "quantity": 1}],
    customer={"email": "user@example.com", "name": "Jane Smith"},
    billing_address={"country": "US"},
    billing_currency="USD",
    return_url="myapp://subscription/activated",
    cancel_url="myapp://subscription/cancelled",
    minimal_address=True,
    customization={"show_order_details": False, "theme": "system"},
    subscription_data={"trial_period_days": 14},
)

See all 11 lines

Bevilja åtkomst när din backend tar emot subscription.active-webhooken, inte när det mobila SDK:t returnerar. Se Subscription Integration Guide för hela webhook-flödet.

On-Demand Mandate - save a card for future variable charges

Använd detta recept för att spara en kunds betalningsmetod för senare debiteringar, till exempel påfyllning av plånbok, pay-as-you-go eller BNPL, utan att visa en prenumerationsetikett. Kunden godkänner betalningsmetoden en gång och du debiterar varierande belopp senare.

Appar som debiterar efter användning följer detta mönster. En astrologiapp kan till exempel debitera ett förgodkänt kort för varje session i stället för enligt ett fast schema.

• Node.js SDK
• Python SDK

// Step 1: Authorize the mandate (no charge yet)
const session = await client.checkoutSessions.create({
  product_cart: [{ product_id: 'pdt_your_subscription_product_id', quantity: 1 }],
  customer: { email: 'user@example.com', name: 'Jane Smith' },
  billing_address: { country: 'US' },
  billing_currency: 'USD',
  return_url: 'myapp://mandate/authorized',
  cancel_url: 'myapp://mandate/cancelled',
  minimal_address: true,
  customization: {
    show_order_details: false,
    show_on_demand_tag: false, // hides the "on-demand" / "subscription" label
    theme: 'system',
  },
  subscription_data: {
    on_demand: { mandate_only: true },
  },
});

// Step 2: Later, charge any amount using the subscription ID
// (received via the subscription.active webhook after mandate authorization)
// await client.subscriptions.charge(subscriptionId, {
//   product_price: 2000,         // $20.00 in cents
//   product_currency: 'USD',
//   product_description: 'Session credits',
// });

See all 26 lines

# Step 1: Authorize the mandate (no charge yet)
session = client.checkout_sessions.create(
    product_cart=[{"product_id": "pdt_your_subscription_product_id", "quantity": 1}],
    customer={"email": "user@example.com", "name": "Jane Smith"},
    billing_address={"country": "US"},
    billing_currency="USD",
    return_url="myapp://mandate/authorized",
    cancel_url="myapp://mandate/cancelled",
    minimal_address=True,
    customization={
        "show_order_details": False,
        "show_on_demand_tag": False,  # hides the "on-demand" / "subscription" label
        "theme": "system",
    },
    subscription_data={"on_demand": {"mandate_only": True}},
)

# Step 2: Later, charge any amount using the subscription ID
# client.subscriptions.charge(
#     subscription_id,
#     product_price=2000,  # $20.00 in cents
#     product_currency="USD",
#     product_description="Session credits",
# )

See all 24 lines

En betalning på begäran måste vara minst 100 i den minsta valutaenheten ($1.00 för USD). API:t avvisar ett lägre product_price med "product_price: value out of range". Om du vill godkänna utan att debitera använder du mandate_only: true enligt exemplet ovan och debiterar minst minimibeloppet senare.

Se On-Demand Subscriptions för hela debiteringsflödet, webhook-händelser och policyer för nya försök.

​

Prenumerationsflöden från mobilen

​

Vanliga återkommande prenumerationer

​

Prenumerationer på begäran

• Ange show_on_demand_tag: false så att checkout-sidan inte visar formuleringar om prenumeration eller betalning på begäran. Kunder som sparar ett kort för påfyllningar förväntar sig inte prenumerationsvillkor.
• När kunden har godkänt medgivandet tar din backend emot subscription.active. Spara subscription_id, eftersom alla senare debiteringar använder det.

​

Prenumeration med kostnadsfri provperiod

​

Uppgraderingar och nedgraderingar

​

Minska avhopp från checkout

​

Optimera formuläret

​

Förifyll kunddata

• Nya kunder: ange customer.email och customer.name från din auth-session.
• Återkommande kunder: ange customer.customer_id för att använda kundens lagrade uppgifter.
• Valuta: skicka billing_currency och billing_address.country tillsammans.

​

Återställningsverktyg

​

Bästa praxis

• Säkerhet: Skicka aldrig med en API-nyckel i appen. Skapa checkout-sessioner på din backend och skicka endast checkout_url till appen.
• Behörighet: Behandla CheckoutResult.status som en UI-ledtråd. Bevilja åtkomst först efter att din backend har bekräftat betalningen.
• Användarupplevelse: Visa ett laddningstillstånd medan din backend skapar sessionen. Behandla inte cancelled som ett fel, eftersom betalningen fortfarande kan ha genomförts.
• Testning: Använd testläge och testkort, och kontrollera retur-URL:ens rundresa på en riktig enhet såväl som i en simulator.
• Konvertering: Ange show_order_details: false och minimal_address: true. Tillsammans flyttar de betalningsmetoderna ovanför vecket och tar bort de flesta adressfälten.
• Valuta: Skicka både billing_currency och billing_address.country. Om du utelämnar någon av dem kan Adaptive Currency välja faktureringsvalutan från kundens IP-adress.
• On-demand-betalning: Ange show_on_demand_tag: false när du använder on-demand-prenumerationer enbart för att spara ett kort. Kunder som fyller på en plånbok förväntar sig inte formuleringar om prenumerationer.
• Återställning: Aktivera Abandoned Cart Recovery i instrumentpanelen för att skicka e-post till kunder som inte slutför checkout.

​

Felsökning

​

Vanliga problem

• Callback anländer aldrig: Schemat i returnUrl måste matcha schemat du registrerade. På Android är det manifestets dodoCallbackScheme-placeholder. På iOS är det URL-typen Info.plist. React Native- och Flutter-appar behöver båda, och i Expo ställer config-pluginen in båda.
• Checkout återgår till webbläsaren i stället för till din app (iOS): Din app vidarebefordrar inte den inkommande URL:en. Anropa DodoCheckout.handleOpenURL(url) från .onOpenURL, scene(_:openURLContexts:) eller en React Native Linking-lyssnare.
• PLATFORM_ERROR på Android: Den vanligaste orsaken är att schemana inte matchar. Det inträffar också när din MainActivity anger android:taskAffinity="" (standardvärdet flutter create), vilket kan göra att vissa Android OEM-versioner tappar den pågående checkouten.
• ALREADY_IN_PROGRESS: En checkout är fortfarande öppen. Vänta tills den föregående har slutförts eller stäng den innan du startar en ny.
• Bygget misslyckas med en olöst placeholder: Du lade till Android SDK men angav inte manifestPlaceholders["dodoCallbackScheme"].
• Betalningen lyckades men åtkomst beviljades inte: Din app beviljar åtkomst baserat på mobilresultatet. Bevilja i stället åtkomst från payment.succeeded- eller subscription.active-webhooken.
• Apple Pay eller Google Pay visas inte på mobilen: Kontrollera om checkout laddas i en inbäddad WebView (WKWebView eller Android WebView). Öppna den med SDK:t eller i systemets webbläsaryta: en Custom Tab på Android eller SFSafariViewController eller ASWebAuthenticationSession på iOS.

​

Ytterligare resurser

• Guide för betalningsintegrering
• Webhook-dokumentation
• Testprocess
• Tekniska vanliga frågor
• Anpassning av checkout-sessioner
• On-Demand-prenumerationer
• Uppgradering/nedgradering av prenumerationer
• Abandoned Cart Recovery
• Customer Portal