Crie uma integração de assinaturas

O SDK da Stripe para iOS é de código aberto, totalmente documentado e compatível com aplicativos que aceitam iOS 13 ou versões mais recentes.

Configure o SDK com sua chave publicável da Stripe na inicialização do aplicativo. Isso permite que seu aplicativo faça solicitações à API da Stripe .

import UIKit
import StripePaymentSheet

@main
class AppDelegate: UIResponder, UIApplicationDelegate {

    func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
        StripeAPI.defaultPublishableKey = 
"pk_test_TYooMQauvdEDq54NiTphI7jx"
        // do any other necessary launch configuration
        return true
    }
}

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.

struct RegisterView: View {
    @State var email = ""
    var body: some View {
        VStack {
            TextField(text: $email) {
                Text("Email")
            }
            Button {
                Task {
                    var request = URLRequest(url: URL(string: "http://localhost:4242/create-customer")!)
                    request.httpMethod = "POST"
                    request.setValue("application/json", forHTTPHeaderField: "Content-Type")
                    request.httpBody = try! JSONEncoder().encode(["email": email])
                    let (data, _) = try! await URLSession.shared.data(for: request)
                    let responseJSON = try! JSONSerialization.jsonObject(with: data)
                    // Return the customer ID here
                    print(responseJSON["customer"])
                }
            } label: {
                Text("Submit")
            }
        }
    }
}

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.

func createSubscription(priceId: String, customerId: String) async -> SubscriptionsResponse {
    var request = URLRequest(url: URL(string: "http://localhost:4242/create-subscription")!)
    request.httpMethod = "POST"
    request.setValue("application/json", forHTTPHeaderField: "Content-Type")
    request.httpBody = try! JSONEncoder().encode(["customerId": customerId, "priceId": priceId])
    let (responseData, _) = try! await URLSession.shared.data(for: request)
    // SubscriptionsResponse is a Decodable struct conforming to the expected response from your backend.
    // It should include the client_secret, as discussed below.
    let subscriptionsResponse = try! JSONDecoder().decode(SubscriptionsResponse.self, from: responseData)
    return subscriptionsResponse
}

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: {type: '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 Payment Sheet para recolher os detalhes do pagamento e ativar a assinatura. Você pode personalizar o Elements para combinar com a aparência do seu aplicativo.

O Payment Sheet coleta com segurança todos os detalhes de pagamento necessários para uma ampla variedade de métodos de pagamento. Saiba mais sobre os métodos de pagamento compatíveis com o Payment Sheet e as assinaturas.

Adicionar o Payment Element ao seu aplicativo

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

struct SubscribeView: View {
    let paymentSheet: PaymentSheet
    @State var isPaymentSheetPresented = false
    init(clientSecret: String) {
        var config = PaymentSheet.Configuration()
        // Set `allowsDelayedPaymentMethods` to true if your business handles
        // delayed notification payment methods like US bank accounts.
        config.allowsDelayedPaymentMethods = true
        config.primaryButtonLabel = "Subscribe for $15/month"
        self.paymentSheet = PaymentSheet(paymentIntentClientSecret: clientSecret, configuration: config)
    }
    var body: some View {
        Button {
            isPaymentSheetPresented = true
        } label: {
            Text("Subscribe")
        }.paymentSheet(isPresented: $isPaymentSheetPresented, paymentSheet: paymentSheet) { result in
            switch result {
            case .completed:
                // Handle completion
            case .canceled:
                break
            case .failed(let error):
                // Handle error
            }
        }
    }
}

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.

O cliente pode sair do seu aplicativo para autenticar (por exemplo, no Safari ou no aplicativo bancário). Para permitir que eles voltem ao seu aplicativo após a autenticação, configure um esquema de URL personalizado e configure seu aplicativo delegado para encaminhar o URL ao SDK. A Stripe não aceita links universais.

// This method handles opening custom URL schemes (for example, "your-app://stripe-redirect")
func scene(_ scene: UIScene, openURLContexts URLContexts: Set<UIOpenURLContext>) {
    guard let url = URLContexts.first?.url else {
        return
    }
    let stripeHandled = StripeAPI.handleURLCallback(with: url)
    if (!stripeHandled) {
        // This was not a Stripe url – handle the URL normally as you would
    }
}

Além disso, defina o returnURL no seu objeto PaymentSheet.Configuration para o URL do seu aplicativo.

var configuration = PaymentSheet.Configuration()
configuration.returnURL = "your-app://stripe-redirect"

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.

Você precisa ouvir alguns eventos para concluir as etapas restantes deste guia. Consulte Eventos de assinatura para obter mais detalhes sobre webhooks específicos de assinatura.

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

func cancelSubscription() {
    var request = URLRequest(url: URL(string: "http://localhost:4242/cancel-subscription")!)
    request.httpMethod = "POST"
    request.setValue("application/json", forHTTPHeaderField: "Content-Type")
    request.httpBody = try! JSONEncoder().encode(["subscriptionId": subscription.id])
    let (subscriptionResponse, _) = try! await URLSession.shared.data(for: request)
    // Update the state to show the subscription has been cancelled
}

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.