Pular para o conteúdo principal

Integração do SDK React Native

O SDK React Native da Dodo Payments permite que você crie experiências de pagamento seguras em seus aplicativos nativos para Android e iOS. Nosso SDK fornece componentes e telas de UI personalizáveis para coletar detalhes de pagamento.

Recursos

Simplified Security

Colete dados sensíveis de pagamento com segurança mantendo a conformidade PCI

Multiple Payment Methods

Aceite diversos métodos de pagamento para expandir o alcance global

Native UI

Telas e elementos nativos para Android e iOS
Atualmente, Apple Pay, Google Pay, Cash App e UPI não são suportados no SDK React Native. Estamos trabalhando ativamente para adicionar suporte a esses métodos de pagamento em versões futuras.

Instalação

1

Install the SDK

Instale o SDK da Dodo Payments usando seu gerenciador de pacotes preferido:
npm install dodopayments-react-native-sdk
2

Platform-specific setup

Execute pod install na pasta do iOS:
cd ios && pod install && npm run ios

Configuração do Lado do Cliente

1

Get Publishable Key

Obtenha sua chave publicável no painel da Dodo Payments. (Distinta para os modos de teste e produção) https://app.dodopayments.com/developer/others
2

Setup Payment Provider

Envolva seu app com o DodoPaymentProvider:
App.tsx
import React from 'react';
import { DodoPaymentProvider } from 'dodopayments-react-native-sdk';
import PaymentScreen from './PaymentScreen';

function App() {
  return (
    <DodoPaymentProvider publishableKey="YOUR_PUBLISHABLE_KEY">
      <PaymentScreen />
    </DodoPaymentProvider>
  );
}

export default App;
Será necessário gerar chaves de API no painel da Dodo Payments. Consulte nosso guia de geração de chaves de API para instruções detalhadas.
3

Create payment utility function

Crie uma função utilitária para buscar os parâmetros de pagamento na sua API de backend:
utils/fetchPaymentParams.ts
const API_URL = 'YOUR_BACKEND_URL'; // Replace with your server URL

const fetchPaymentParams = async () => {
  const response = await fetch(`${API_URL}/create-payment`, {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
    },
  });
  
  if (!response.ok) {
    throw new Error('Failed to fetch payment parameters');
  }
  
  return await response.json();
};

export default fetchPaymentParams;
Esta função pressupõe que você tenha um endpoint de backend que cria intents de pagamento e retorna um client secret. Garanta que seu backend esteja configurado adequadamente para lidar com a criação de pagamentos. Veja nosso Tutorial de Integração da API para exemplos de configuração do backend.
4

Implement the payment screen

Crie sua tela de pagamento usando o hook useCheckout. Aqui está uma implementação completa:
PaymentScreen.tsx
import React from 'react';
import { View, Text, useColorScheme } from 'react-native';
import { useCheckout, type sessionParams } from 'dodopayments-react-native-sdk';
import fetchPaymentParams from './utils/fetchPaymentParams';

const PaymentScreen = () => {
  const { initPaymentSession, presentPaymentSheet } = useCheckout();
  const [error, setError] = React.useState('');
  const [message, setMessage] = React.useState('');
  const [loading, setLoading] = React.useState(false);
  const [showSuccessScreen, setShowSuccessScreen] = React.useState(false);
  const isDarkMode = useColorScheme() === 'dark';

  const processPayment = async () => {
    setLoading(true);
    setMessage('');
    setError('');

    try {
      // 1. Get payment parameters from your backend
      const key = await fetchPaymentParams();
      
      // 2. Initialize payment session
      const paymentSheetParamsResult = await initPaymentSession({
        clientSecret: key.clientSecret,
      });
      
      // 3. Configure and present payment sheet
      const params: sessionParams = {
        ...(paymentSheetParamsResult as sessionParams),
        configuration: {
          appearance: {
            themes: isDarkMode ? 'dark' : 'light',
            primaryButton: {
              colors: {
                light: {
                  background: 'green',
                  componentBorder: 'green',
                  placeholderText: 'yellow',
                },
                dark: {
                  background: 'green',
                  componentBorder: 'green',
                  placeholderText: 'yellow',
                },
              },
              shapes: {
                borderRadius: 30,
                borderWidth: 3,
              },
            },
          },
          mode: 'test', // DEFAULTS TO TEST MODE
        },
      };

      const paymentSheetResponse = await presentPaymentSheet(params);

      // 4. Handle payment result
      switch (paymentSheetResponse?.status) {
        case 'cancelled':
          setError('Payment cancelled by user.');
          break;
        case 'succeeded':
          setMessage('');
          setShowSuccessScreen(true);
          break;
        case 'failed':
          setError('Payment failed : \n' + paymentSheetResponse?.message);
          break;
        default:
          setError(paymentSheetResponse?.message);
          setMessage('');
      }
    } catch (err) {
      setError('Failed to process payment');
    } finally {
      setLoading(false);
    }
  };

  return (
    <View>
      <Button 
        onPress={processPayment}
        disabled={loading}
        title={loading ? 'Processing...' : 'Pay Now'}
      />
      {error && <Text style={{ color: 'red' }}>{error}</Text>}
      {message && <Text style={{ color: 'green' }}>{message}</Text>}
      {showSuccessScreen && (
        <PaymentSuccessScreen
          amount={total}
          onContinue={() => setShowSuccessScreen(false)}
        />
      )}
    </View>
  );
};

export default PaymentScreen;
Para exemplos completos com estilização, tratamento de erros e opções de personalização, confira nossos repositórios de demonstração:

Opções de Configuração

Parâmetros da Sessão

clientSecret
string
obrigatório
O client secret do seu payment intent, obtido pela API de pagamento único ou de assinatura.
mode
string
obrigatório
O modo da sessão de pagamento (teste ou produção).
configuration.appearance
object
Opções de personalização para a aparência da folha de pagamento
configuration.appearance.themes
string
Modo do tema: 'light' ou 'dark'

Personalização da Aparência

Você pode personalizar o Checkout Unificado do React Native para combinar com o design do seu app modificando cores, fontes e mais por meio do parâmetro appearance ao chamar initPaymentSession().

Personalização de Cores

Cada categoria de cor determina a cor de um ou mais componentes na interface do usuário. Por exemplo, primary define a cor do botão Pagar.
Categoria de corUso
primaryCor primária para o botão Pagar e itens selecionados
backgroundCor de fundo da página de pagamento
componentBackgroundCor de fundo para campos, abas e outros componentes
componentBorderCor da borda externa para campos, abas e outros componentes
componentDividerCor da borda interna (bordas compartilhadas) dos componentes
primaryTextCor do texto do cabeçalho
secondaryTextCor do texto dos rótulos dos campos
componentTextCor do texto dos campos (por exemplo, número do cartão, CEP)
placeholderTextCor do texto de espaço reservado dos campos
iconCor dos ícones (por exemplo, botão fechar)
errorCor para mensagens de erro e ações destrutivas
Exemplo de configuração com suporte a modos claro e escuro:
const appearance = {
  colors: {
    light: {
      primary: '#F8F8F2',
      background: '#ffffff',
      componentBackground: '#E6DB74',
      componentBorder: '#FD971F',
      componentDivider: '#FD971F',
      primaryText: '#F8F8F2',
      secondaryText: '#75715E',
      componentText: '#AE81FF',
      placeholderText: '#E69F66',
      icon: '#F92672',
      error: '#FF0000',
    },
    dark: {
      primary: '#00ff0099',
      background: '#ff0000',
      componentBackground: '#ff0080',
      componentBorder: '#62ff08',
      componentDivider: '#d6de00',
      primaryText: '#5181fc',
      secondaryText: '#ff7b00',
      componentText: '#00ffff',
      placeholderText: '#00ffff',
      icon: '#f0f0f0',
      error: '#0f0f0f',
    },
  },
};

Personalização de Forma

Você pode personalizar o raio da borda, a largura da borda e a sombra usadas em toda a interface de pagamento:
const appearance = {
  shapes: {
    borderRadius: 10, // Border radius for input fields, tabs, and components
    borderWidth: 1,   // Border width for components
  },
};

Personalização Específica de Componentes

Você pode personalizar componentes de UI específicos, como o botão primário (botão de Pagamento). Essas configurações têm precedência sobre as configurações de aparência globais:
const appearance = {
  primaryButton: {
    colors: {
      background: '#000000',
      text: '#ffffff',
      border: '#ff00ff',
    },
    shapes: {
      borderRadius: 10,
      borderWidth: 1.5,
    },
  },
};
Para aplicar essas personalizações, inclua-as na configuração da sua sessão de pagamento:
const params: sessionParams = {
  ...paymentSheetParams,
  configuration: {
    appearance: {
      themes: isDarkMode ? 'dark' : 'light',
      ...appearance, // Include your custom appearance settings
    },
  },
};

Tratamento de Erros

Trate diferentes estados de pagamento na sua função de checkout:
const handlePaymentResult = (paymentSheetResponse) => {
  switch (paymentSheetResponse?.status) {
    case 'cancelled':
      // User cancelled the payment
      console.log('Payment cancelled by user');
      break;
    case 'succeeded':
      // Payment completed successfully
      console.log('Payment succeeded');
      // Navigate to success screen or update UI
      break;
    case 'failed':
      // Payment failed
      console.log('Payment failed:', paymentSheetResponse?.message);
      // Show error message to user
      break;
    default:
      console.log('Unknown payment status:', paymentSheetResponse?.status);
  }
};
  • Problemas de conectividade de rede: garanta conexão de internet estável
  • Client secret inválido: verifique se o backend está gerando intents de pagamento válidos
  • Dependências peer faltando: instale todas as dependências necessárias
  • Configuração específica da plataforma: conclua as etapas de configuração do iOS e Android
  • Erros da API: consulte nossa Referência de Códigos de Erro para tratamento detalhado de erros
  • Ative o registro em modo debug durante o desenvolvimento
  • Verifique as requisições de rede para o seu backend
  • Confirme se as chaves de API estão configuradas corretamente
  • Teste em plataformas iOS e Android
  • Revise nossas Perguntas Frequentes Técnicas para problemas comuns
  • Utilize corretamente o Modo de Teste vs Modo Ao Vivo

Métodos de Pagamento de Teste

Use números de cartão de teste durante o desenvolvimento para verificar sua integração sem processar pagamentos reais. Saiba mais sobre nosso processo de testes e os ambientes de teste disponíveis.