Aceitar um pagamento

Primeiro, você precisa de uma conta Stripe. Inscreva-se aqui.

Lado do servidor

Esta integração exige que os endpoints do seu servidor se comuniquem com a API da Stripe. Use as bibliotecas oficiais para acessar a API da Stripe pelo seu servidor:

# Available as a gem
sudo gem install stripe

# If you use bundler, you can add this line to your Gemfile
gem 'stripe'

Lado do cliente

O SDK do React Native é de código aberto e totalmente documentado. Internamente, utiliza as SDKs de iOS nativo e Android. Para instalar o SDK do React Native da Stripe, execute um dos seguintes comandos no diretório do seu projeto (dependendo de qual gerenciador de pacotes você usa):

yarn add @stripe/stripe-react-native

Em seguida, instale algumas outras dependências necessárias:

• Para iOS, vá para o diretório ios e execute pod install para garantir a instalação das dependências nativas necessárias.
• Para Android, não há mais dependências para instalar.

Inicialização da Stripe

Para inicializar a Stripe no aplicativo React Native, insira sua tela de pagamento com o componente StripeProvider ou use o método de inicialização initStripe. Somente a chave da API publicável em publishableKey é necessária. O exemplo a seguir mostra como inicializar a Stripe usando o componente StripeProvider.

import { useState, useEffect } from 'react';
import { StripeProvider } from '@stripe/stripe-react-native';

function App() {
  const [publishableKey, setPublishableKey] = useState('');

  const fetchPublishableKey = async () => {
    const key = await fetchKey(); // fetch key from your server here
    setPublishableKey(key);
  };

  useEffect(() => {
    fetchPublishableKey();
  }, []);

  return (
    <StripeProvider
      publishableKey={publishableKey}
      merchantIdentifier="merchant.identifier" // required for Apple Pay
      urlScheme="your-url-scheme" // required for 3D Secure and bank redirects
    >
      {/* Your app code here */}
    </StripeProvider>
  );
}

Veja suas configurações de formas de pagamento e habilite as formas de pagamento que deseja aceitar. Você precisa de pelo menos uma forma de pagamento habilitada para criar um PaymentIntent.

Por padrão, a Stripe habilita cartões e outras formas de pagamento predominantes que podem ajudar você a alcançar mais clientes, mas recomendamos ativar outras formas de pagamento que sejam relevantes para sua empresa e seus clientes. Consulte Suporte a formas de pagamento para saber mais sobre os produtos e formas de pagamento aceitos, e nossa página de preços para ver as tarifas.

Esta integração usa três objetos da API da Stripe:

1. PaymentIntent: A Stripe usa isso para representar sua intenção de coletar o pagamento de um cliente, acompanhando suas tentativas de cobrança e alterações no estado do pagamento durante todo o processo.

2. (Opcional) Customer: Para configurar uma forma de pagamento para pagamentos futuros, vincule-a a um Customer. Crie um objeto Customer quando o cliente abrir uma conta na sua empresa. Se o cliente pagar como convidado, você pode criar o objeto Customer antes do pagamento e associá-lo à sua representação interna da conta do cliente, mais tarde.

3. (Opcional) Chave Efêmera de Cliente: as informações sobre o objeto Customer são confidenciais e não podem ser obtidas diretamente por um apliativo. Uma Chave Efêmera concede acesso temporário ao Cliente para o SDK.

Por motivos de segurança, seu aplicativo não pode criar esses objetos. Em vez disso, adicione um endpoint ao seu servidor que:

1. Recuperar ou criar um Customer.
2. Criar uma chave efêmera para o Customer.
3. Cria um PaymentIntent com o valor, a moeda e o cliente. Também é possível incluir opcionalmente o parâmetro automatic_payment_methods. A Stripe habilita sua funcionalidade por padrão na versão mais recente da API.
4. Retorna o segredo do cliente do Payment Intent, o secret da chave efêmera, o id do cliente e sua chave publicável ao aplicativo.

As formas de pagamento mostradas aos clientes durante o processo de checkout também são incluídas no PaymentIntent. Você pode permitir que a Stripe obtenha as formas de pagamento das configurações do Dashboard ou listá-las manualmente. Independentemente da opção escolhida, saiba que a moeda passada no PaymentIntent filtra as formas de pagamento mostradas para o cliente. Por exemplo, se você passar EUR no eur e a OXXO estiver ativada no Dashboard, a OXXO não será exibida ao cliente porque a OXXO não aceita pagamentos em eur.

Se sua integração não exige uma opção baseada em código para oferecer formas de pagamento, a Stripe recomenda a opção automática. Isso ocorre porque a Stripe avalia a moeda, as restrições de forma de pagamento e outros parâmetros para determinar a lista de formas de pagamento aceitas. Priorizamos as formas de formas de pagamento que aumentam a conversão e que são mais relevantes para a moeda e a localização do cliente.

# Create a Customer (use an existing Customer ID if this is a returning customer)
curl https://api.stripe.com/v1/customers \
  -u 
sk_test_BQokikJOvBiI2HlWgH4olfQ2
: \
  -X "POST" \
  -H "Stripe-Account: {{CONNECTED_ACCOUNT_ID}}"

# Create an Ephemeral Key for the Customer
curl https://api.stripe.com/v1/ephemeral_keys \
  -u 
sk_test_BQokikJOvBiI2HlWgH4olfQ2
: \
  -H "Stripe-Version: 2025-09-30.clover" \
  -H "Stripe-Account: 2025-09-30.clover" \
  -X "POST" \
  -d "customer"="{{CUSTOMER_ID}}" \

# Create a PaymentIntent
curl https://api.stripe.com/v1/payment_intents \
  -u 
sk_test_BQokikJOvBiI2HlWgH4olfQ2
: \
  -X "POST" \
  -d "customer"="{{CUSTOMER_ID}}" \
  -d "amount"=1099 \
  -d "currency"="eur" \
  # In the latest version of the API, specifying the `automatic_payment_methods` parameter
  # is optional because Stripe enables its functionality by default.
  -d "automatic_payment_methods[enabled]"=true \

Antes de exibir o Element Pagamento para dispositivos móveis, a página de checkout deve:

• Mostrar os produtos sendo comprados e o valor total
• Coletar todos os dados de entrega necessários
• Incluir um botão de checkout para apresentar a IU da Stripe

No checkout do aplicativo, faça uma solicitação de rede para o endpoint de backend criado por você na etapa anterior e chame o initPaymentSheet do hook useStripe.

export default function CheckoutScreen() {
  const { initPaymentSheet, presentPaymentSheet } = useStripe();
  const [loading, setLoading] = useState(false);

  const fetchPaymentSheetParams = async () => {
    const response = await fetch(`${API_URL}/payment-sheet`, {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
      },
    });
    const { paymentIntent, ephemeralKey, customer } = await response.json();

    return {
      paymentIntent,
      ephemeralKey,
      customer,
    };
  };

  const initializePaymentSheet = async () => {
    const {
      paymentIntent,
      ephemeralKey,
      customer,
    } = await fetchPaymentSheetParams();

    const { error } = await initPaymentSheet({
      merchantDisplayName: "Example, Inc.",
      customerId: customer,
      customerEphemeralKeySecret: ephemeralKey,
      paymentIntentClientSecret: paymentIntent,
      // Set `allowsDelayedPaymentMethods` to true if your business can handle payment
      //methods that complete payment after a delay, like SEPA Debit and Sofort.
      allowsDelayedPaymentMethods: true,
      defaultBillingDetails: {
        name: 'Jane Doe',
      }
    });
    if (!error) {
      setLoading(true);
    }
  };

  const openPaymentSheet = async () => {
    // see below
  };

  useEffect(() => {
    initializePaymentSheet();
  }, []);

  return (
    <Screen>
      <Button
        variant="primary"
        disabled={!loading}
        title="Checkout"
        onPress={openPaymentSheet}
      />
    </Screen>
  );
}

Quando o cliente tocar no botão Checkout, chame presentPaymentSheet() para abrir a descrição. Depois que o cliente finalizar o pagamento, a descrição será descartada e a promessa será resolvida com um StripeError<PaymentSheetError> opcional.

export default function CheckoutScreen() {
  // continued from above

  const openPaymentSheet = async () => {
    const { error } = await presentPaymentSheet();

    if (error) {
      Alert.alert(`Error code: ${error.code}`, error.message);
    } else {
      Alert.alert('Success', 'Your order is confirmed!');
    }
  };

  return (
    <Screen>
      <Button
        variant="primary"
        disabled={!loading}
        title="Checkout"
        onPress={openPaymentSheet}
      />
    </Screen>
  );
}

Se não houver erro, informe ao usuário que está tudo pronto (por exemplo, exibindo uma tela de confirmação de pedido).

Configurar allowsDelayedPaymentMethods como verdadeiro permite formas de pagamento de notificação assíncrona como contas bancárias dos EUA. Para essas formas de pagamento, o status final do pagamento não é conhecido quando o PaymentSheet é concluído, sendo efetivado ou não posteriormente. Se você aceitar esses tipos de formas de pagamento, informe o cliente que seu pedido está confirmado e somente processe o pedido (por exemplo, fazendo o envio do produto) quando o pagamento for bem-sucedido.

Quando um cliente sair do seu aplicativo (por exemplo, para fazer a autenticação no Safari ou no aplicativo do banco), forneça uma opção para que ele retorne automaticamente ao seu aplicativo. Muitos tipos de formas de pagamento exigem um URL de retorno. Se você não fornecer um, não poderemos apresentar formas de pagamento que exijam um URL de retorno aos seus usuários, mesmo que você os habilite.

Para fornecer um URL de retorno:

1. Cadastre um URL personalizado. Links universais não são aceitos.
2. Configurar seu URL personalizado.
3. Configure seu componente-raiz para encaminhar o URL ao SDK da Stripe, conforme mostrado abaixo.

import { useEffect, useCallback } from 'react';
import { Linking } from 'react-native';
import { useStripe } from '@stripe/stripe-react-native';

export default function MyApp() {
  const { handleURLCallback } = useStripe();

  const handleDeepLink = useCallback(
    async (url: string | null) => {
      if (url) {
        const stripeHandled = await handleURLCallback(url);
        if (stripeHandled) {
          // This was a Stripe URL - you can return or add extra handling here as you see fit
        } else {
          // This was NOT a Stripe URL – handle as you normally would
        }
      }
    },
    [handleURLCallback]
  );

  useEffect(() => {
    const getUrlAsync = async () => {
      const initialUrl = await Linking.getInitialURL();
      handleDeepLink(initialUrl);
    };

    getUrlAsync();

    const deepLinkListener = Linking.addEventListener(
      'url',
      (event: { url: string }) => {
        handleDeepLink(event.url);
      }
    );

    return () => deepLinkListener.remove();
  }, [handleDeepLink]);

  return (
    <View>
      <AwesomeAppComponent />
    </View>
  );
}

Além disso, defina o returnURL quando chamar o método initPaymentSheet:

await initPaymentSheet({
  ...
  returnURL: 'your-app://stripe-redirect',
  ...
});

Para obter mais informações sobre esquemas de URL nativos, consulte a documentação do Android e do iOS.

Stripe envia um evento payment_intent.succeeded quando o pagamento é concluído. Use a ferramenta Dashboard webhook ou siga o guia de webhooks para receber esses eventos e executar ações, como enviar um e-mail de confirmação do pedido ao cliente, registrar a venda em um banco de dados ou iniciar um fluxo de trabalho de envio.

Escute esses eventos em vez de aguardar um retorno de chamada do cliente. No cliente, o consumidor pode fechar a janela do navegador ou sair do aplicativo antes da execução do retorno de chamada, o que permite que clientes mal-intencionados manipulem a resposta. Configurar sua integração para escutar eventos assíncronos é o que permite a você aceitar diferentes tipos de formas de pagamento com uma única integração.

Além de gerenciar o evento payment_intent.succeeded, recomendamos gerenciar esses outros eventos ao coletar pagamentos com o Element Pagamento:

Consulte Testes para obter mais informações sobre como testar sua integração.