Guia de Integração Móvel

​

Pré-requisitos

• Conta do Dodo Payments: Conta de comerciante ativa com acesso à API
• Credenciais da API: Chave de API e chave secreta de webhook do seu dashboard
• Projeto de aplicativo mobile: Aplicativo Android, iOS, React Native ou Flutter
• Servidor de backend: Para lidar com a criação de sessões de checkout com segurança

​

Fluxo de integração

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

​

Escolha seu SDK

​

Registrando um esquema de URL de callback

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>

npx expo install expo-build-properties

{
  "expo": {
    "plugins": [
      [
        "expo-build-properties",
        { "android": { "manifestPlaceholders": { "dodoCallbackScheme": "myapp" } } }
      ]
    ],
    "ios": {
      "infoPlist": {
        "CFBundleURLTypes": [{ "CFBundleURLSchemes": ["myapp"] }]
      }
    }
  }
}

​

Práticas recomendadas

• Segurança: nunca inclua uma chave de API no seu aplicativo. Crie sessões de checkout no seu backend e passe ao cliente apenas o checkout_url resultante.
• Autoridade: trate CheckoutResult.status como uma indicação de UI. Conceda acesso somente depois que seu backend confirmar o pagamento.
• Experiência do usuário: exiba um estado de carregamento enquanto seu backend cria a sessão e trate cancelled como um resultado normal, não como um erro.
• Testes: use o modo de teste e cartões de teste, e verifique o ciclo completo da URL de retorno em um dispositivo real e também em um simulador.

​

Solução de problemas

​

Problemas comuns

• O callback nunca chega: o esquema em returnUrl deve corresponder ao que você registrou. No Android, esse é o placeholder de manifesto dodoCallbackScheme; no iOS e no React Native, é o tipo de URL Info.plist.
• O checkout retorna ao navegador em vez de retornar ao seu aplicativo (iOS): você não encaminhou a URL recebida. Chame DodoCheckout.handleOpenURL(url) de .onOpenURL, scene(_:openURLContexts:) ou de um listener Linking do React Native.
• PLATFORM_ERROR no Android: na maioria das vezes, isso indica uma incompatibilidade de esquemas. Também pode ocorrer se seu MainActivity definir android:taskAffinity="" (o padrão flutter create), o que pode fazer com que alguns builds de OEM percam o checkout em andamento.
• ALREADY_IN_PROGRESS: ainda há um checkout aberto. Aguarde ou descarte o anterior antes de iniciar outro.
• O build falha com um placeholder não resolvido: você adicionou o Android SDK, mas nunca definiu manifestPlaceholders["dodoCallbackScheme"].
• O pagamento foi bem-sucedido, mas o acesso não foi concedido: isso é esperado se você estiver usando o resultado mobile como referência. Conceda o acesso a partir do webhook payment.succeeded / subscription.active.

​

Recursos adicionais

• Guia de integração de pagamentos
• Documentação de webhook
• Processo de testes
• Perguntas frequentes técnicas