Crie uma integração de assinaturas

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:

• For iOS, go to the ios directory and run pod install to ensure that you also install the required native dependencies.
• 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>
  );
}

Em seguida, instale a Stripe CLI. A CLI fornece testes de webhooks, e você pode executá-la para fazer chamadas de API para a Stripe. Este guia mostra a você como usar a CLI para configurar um modelo de preços em uma seção posterior.

# Install Homebrew to run this command: https://brew.sh/
brew install stripe/stripe-cli/stripe

# Connect the CLI to your dashboard
stripe login

Para obter opções de instalação adicionais, consulte Comece a usar o Stripe CLI.

Crie seus produtos e preços usando o Dashboard ou a Stripe CLI.

Este exemplo usa um serviço de preço fixo com duas opções diferentes de nível de serviço: Básico e Premium. Para cada opção de nível de serviço, você precisa criar um produto e um preço recorrente. (Se quiser adicionar uma cobrança avulsa para um item como tarifa de configuração, crie um terceiro produto com um preço avulso. Para simplificar, este exemplo não inclui uma cobrança avulsa.)

Neste exemplo, o faturamento de cada produto é mensal. O produto básico custa 5 USD e o produto Premium custa 15 USD.

A Stripe precisa de um cliente para cada assinatura. No front-end do seu aplicativo, colete todas as informações necessárias dos seus usuários e passe-as ao back-end.

Se precisar coletar detalhes de endereço, o Address Element permite coletar um endereço de entrega ou cobrança para seus clientes. Saiba mais o Address Element na página Address Element.

import React from 'react';
import {View, TextInput, StyleSheet, Button, Platform} from 'react-native';

function RegisterView() {
  const [email, setEmail] = React.useState('');

  const createCustomer = async () => {
    const apiEndpoint =
      Platform.OS === 'ios' ? 'http://localhost:4242' : 'http://10.0.2.2:4567';
    const response = await fetch(`${apiEndpoint}/create-customer`, {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
      },
      body: JSON.stringify({
        email: email,
      }),
    });
    if (response.status === 200) {
      const customer = await response.json();
      console.log(customer);
    }
  };

  return (
    <View>
      <TextInput
        style={styles.input}
        placeholder="Email"
        value={email}
        onChangeText={setEmail}
      />
      <Button
        title="Register"
        onPress={async () => {
          await createCustomer();
        }}
      />
    </View>
  );
}

const styles = StyleSheet.create({
  input: {
    height: 40,
    margin: 12,
    borderWidth: 1,
    padding: 10,
  },
});

export default RegisterView;

No servidor, crie o objeto do cliente Stripe.

curl https://api.stripe.com/v1/customers \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -d email={{CUSTOMER_EMAIL}} \
  -d name={{CUSTOMER_NAME}} \
  -d "shipping[address][city]"=Brothers \
  -d "shipping[address][country]"=US \
  -d "shipping[address][line1]"="27 Fredrick Ave" \
  -d "shipping[address][postal_code]"=97712 \
  -d "shipping[address][state]"=CA \
  -d "shipping[name]"={{CUSTOMER_NAME}} \
  -d "address[city]"=Brothers \
  -d "address[country]"=US \
  -d "address[line1]"="27 Fredrick Ave" \
  -d "address[postal_code]"=97712 \
  -d "address[state]"=CA

Permita que seu novo cliente escolha um plano e crie a assinatura. Neste guia, ele escolhe Básico ou Premium.

No seu aplicativo, passe o ID do preço selecionado e o ID do registro do cliente ao back-end.

const createSubscription = async (priceId, customerId) => {
  const apiEndpoint =
    Platform.OS === 'ios' ? 'http://localhost:4242' : 'http://10.0.2.2:4567';
  const response = await fetch(`${apiEndpoint}/create-subscription`, {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      priceId: priceId,
      customerId: customerId,
    }),
  });
  if (response.status === 200) {
    const subscription = await response.json();
    return subscription;
  }
};

No back-end, crie a assinatura com status incomplete usando payment_behavior=default_incomplete. Em seguida, retorne o client_secret do primeiro Payment Intent da assinatura ao frontend para concluir o pagamento expandindo o confirmation_secret na última fatura da assinatura.

Para habilitar comportamento de assinatura aprimorado, defina billing_mode[type] como flexible. Você deve usar a versão 2025-06-30.basil ou posterior da API da Stripe.

Defina save_default_payment_method como on_subscription para salvar a forma de pagamento como o padrão para uma assinatura quando um pagamento for bem-sucedido. Salvar uma forma de pagamento padrão aumenta o sucesso de futuros pagamentos de assinatura.

# Set your secret key. Remember to switch to your live secret key in production.
# See your keys here: https://dashboard.stripe.com/apikeys
Stripe.api_key = 
'sk_test_BQokikJOvBiI2HlWgH4olfQ2'

post '/create-subscription' do
  content_type 'application/json'
  data = JSON.parse(request.body.read)
  customer_id = cookies[:customer]
  price_id = data['priceId']

  # Create the subscription. Note we're expanding the Subscription's
  # latest invoice and that invoice's confirmation_secret
  # so we can pass it to the front end to confirm the payment
  subscription = Stripe::Subscription.create(
    customer: customer_id,
    items: [{
      price: price_id,
    }],
    payment_behavior: 'default_incomplete',
    payment_settings: {save_default_payment_method: 'on_subscription'},
    billing_mode: 'flexible',
    expand: ['latest_invoice.confirmation_secret']
  )

  { subscriptionId: subscription.id, clientSecret: subscription.latest_invoice.confirmation_secret.client_secret }.to_json
end

Neste ponto, a assinatura fica inactive e aguardando pagamento. Veja este exemplo de resposta. Os campos mínimos para armazenar são destacados, mas armazenam qualquer coisa que o aplicativo acessa com frequência.

{
  "id": "sub_JgRjFjhKbtD2qz",
  "object": "subscription",
  "application_fee_percent": null,
  "automatic_tax": {
    "disabled_reason": null,
    "enabled": false,
    "liability": "null"
  },
  "billing_cycle_anchor": 1623873347,

Use o Mobile Payment Element para coletar dados de pagamento e ativar a assinatura. Você pode personalizar o Elements para corresponder à aparência do seu aplicativo.

O Mobile Payment Element coleta com segurança todos os dados de pagamento necessários para várias formas de pagamento. Saiba mais sobre as formas de pagamento aceitas para Mobile Payment Element e Subscriptions.

Adicionar o Payment Element ao seu aplicativo

Inicialize e apresente o Mobile Payment Element usando a classe PaymentSheet.

import React from 'react';
import {useStripe, PaymentSheetError} from '@stripe/stripe-react-native';
import {View, Button} from 'react-native';

function SubscribeView({clientSecret}) {
  const {initPaymentSheet, presentPaymentSheet} = useStripe();

  React.useEffect(() => {
    const initializePaymentSheet = async () => {
      const {error} = await initPaymentSheet({
        paymentIntentClientSecret: clientSecret,
        returnURL: 'stripe-example://payment-sheet',
        // Set `allowsDelayedPaymentMethods` to true if your business handles
        // delayed notification payment methods like US bank accounts.
        allowsDelayedPaymentMethods: true,
      });
      if (error) {
        // Handle error
      }
    };

    initializePaymentSheet();
  }, [clientSecret, initPaymentSheet]);

  return (
    <View>
      <Button
        title="Subscribe"
        onPress={async () => {
          const {error} = await presentPaymentSheet();
          if (error) {
            if (error.code === PaymentSheetError.Failed) {
              // Handle failed
            } else if (error.code === PaymentSheetError.Canceled) {
              // Handle canceled
            }
          } else {
            // Payment succeeded
          }
        }}
      />
    </View>
  );
}

export default SubscribeView;

O Mobile Payment Element renderiza uma planilha que permite ao cliente selecionar uma forma de pagamento. O formulário coleta automaticamente todos os dados de pagamento necessários da forma de pagamento selecionada.

Configurar allowsDelayedPaymentMethods como verdadeiro permite formas de pagamento de notificação posterior 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.

Você pode personalizar o Payment Element conforme o design do seu aplicativo usando a propriedade appearance do seu objeto PaymentSheet.Configuration.

Confirmar pagamento

O Mobile Payment Element cria um PaymentMethod e confirma o primeiro PaymentIntent da assinatura incompleta, resultando em uma cobrança. Se a Autenticação forte de cliente (SCA) for necessária para o pagamento, o Payment Element gerenciará o processo de autenticação antes de confirmar o PaymentIntent.

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.

Para concluir a integração, é preciso processar os webhooks enviados pela Stripe. Os eventos são acionados sempre que o estado dentro da Stripe muda, como assinaturas criando novas faturas. Em seu aplicativo, configure um gerenciador de HTTP para aceitar uma solicitação POST contendo o evento de webhook e verifique a assinatura do evento:

# Set your secret key. Remember to switch to your live secret key in production.
# See your keys here: https://dashboard.stripe.com/apikeys
Stripe.api_key = 
'sk_test_BQokikJOvBiI2HlWgH4olfQ2'

post '/webhook' do
  # You can use webhooks to receive information about asynchronous payment events.
  # For more about our webhook events check out https://stripe.com/docs/webhooks.
  webhook_secret = ENV['STRIPE_WEBHOOK_SECRET']
  payload = request.body.read
  if !webhook_secret.empty?

Durante o desenvolvimento, use o Stripe CLI para observar webhooks e encaminhá-los ao seu aplicativo. Execute o seguinte em um novo terminal enquanto seu aplicativo de desenvolvimento está sendo executado:

stripe listen --forward-to localhost:4242/webhook

Para produção, configure um URL de endpoint de webhook no Dashboard ou use o Webhook Endpoints API.

You need to listen to a few events to complete the remaining steps in this guide. See Subscription events for more details about subscription-specific webhooks.

Agora que a assinatura está ativa, forneça ao usuário o acesso ao seu serviço. Para fazer isso, escute os eventos customer.subscription.created, customer.subscription.updated e customer.subscription.deleted. Esses eventos apresentam um objeto de assinatura que contém um campo status indicando se a assinatura está ativa, vencida ou cancelada. Consulte o ciclo de vida da assinatura para obter uma lista completa de status.

No seu gerenciador de webhooks:

1. Verifique o status da assinatura. Se estiver active, o usuário pagou o produto.
2. Confira o produto que o cliente assinou e conceda acesso ao serviço. Verificar o produto em vez do preço proporciona mais flexibilidade, caso seja necessário alterar os preços ou o intervalo de faturamento.
3. Armazene product.id, subscription.id e subscription.status no seu banco de dados junto com o customer.id que você já salvou. Verifique esse registro ao determinar quais recursos devem ser habilitados para o usuário em seu aplicativo.

O estado de uma assinatura pode mudar a qualquer momento durante sua vida útil, mesmo se o aplicativo não fizer nenhuma chamada direta para a Stripe. Por exemplo, uma renovação pode falhar porque o cartão de crédito venceu, o que coloca a assinatura em estado vencido. Ou, se você implementar o portal do cliente, um usuário pode cancelar a assinatura sem visitar diretamente seu aplicativo. A implementação correta do manipulador mantém o estado do aplicativo em sincronia com Stripe.

É comum permitir que os clientes cancelem suas assinaturas. Este exemplo adiciona uma opção de cancelamento à página de configurações da conta.

O exemplo coleta o ID da assinatura no front-end, mas o seu aplicativo pode obter essas informações do seu banco de dados para seu usuário conectado.

Configurações da conta com a capacidade de cancelar a assinatura

const cancelSubscription = async subscriptionId => {
  const apiEndpoint =
    Platform.OS === 'ios' ? 'http://localhost:4242' : 'http://10.0.2.2:4567';
  const response = await fetch(`${apiEndpoint}/cancel-subscription`, {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      subscriptionId: subscriptionId,
    }),
  });
  if (response.status === 200) {
    const subscription = await response.json();
    return subscription;
  }
};

No back-end, defina o endpoint para a chamada do seu aplicativo.

# Set your secret key. Remember to switch to your live secret key in production.
# See your keys here: https://dashboard.stripe.com/apikeys
Stripe.api_key = 
'sk_test_BQokikJOvBiI2HlWgH4olfQ2'

post '/cancel-subscription' do
  content_type 'application/json'
  data = JSON.parse request.body.read

  deleted_subscription = Stripe::Subscription.cancel(data['subscriptionId'])

  deleted_subscription.to_json
end

Seu back-end recebe um evento customer.subscription.deleted.

Após o cancelamento da assinatura, remova do banco de dados o ID de assinatura da Stripe que você armazenou anteriormente e limite o acesso ao seu serviço.

Depois de serem canceladas, as assinaturas não podem ser reativadas. Obtenha dados de faturamento atualizados do seu cliente, atualize a forma de pagamento padrão e crie uma nova assinatura com o registro de cliente existente.

Testar formas de pagamento

Use a tabela a seguir para testar diferentes formas de pagamento e cenários.

Monitorar eventos

Configure webhooks para ouvir eventos de alteração de assinatura, como atualizações e cancelamentos. Saiba mais sobre webhooks de assinatura. É possível visualizar eventos no Dashboard ou com a Stripe CLI.

Saiba mais em testar sua integração com o Billing.