Salvar dados de pagamento durante um pagamento no aplicativo

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

Lado do servidor

Esta integração exige que os endpoints do seu servidor se comuniquem com a API da Stripe. Use nossas bibliotecas oficiais para acessar a API da Stripe partir do 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 da Stripe para iOS é de código aberto, totalmente documentado e compatível com aplicativos que aceitam iOS 13 ou versões mais recentes.

Os pagamentos com cartão são habilitados por padrão. Veja as configurações de formas de pagamento para habilitar outras formas de pagamento que você quer aceitar.

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. 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. 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, bem como o setup_future_usage . 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"

# 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" \
  -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" \
  -d "setup_future_usage"="off_session" \
  # 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 \

Para exibir o Payment Element para dispositivos móveis na tela de checkout, não se esqueça de:

• Mostrar os produtos que o cliente está comprando e o valor total
• Usar o Address Element para coletar todos os dados de envio necessários do cliente
• Adicionar um botão de checkout para exibir a IU da Stripe

import UIKit
import StripePaymentSheet

class CheckoutViewController: UIViewController {
  @IBOutlet weak var checkoutButton: UIButton!
  var paymentSheet: PaymentSheet?
  let backendCheckoutUrl = URL(string: "Your backend endpoint/payment-sheet")! // Your backend endpoint

  override func viewDidLoad() {
    super.viewDidLoad()

    checkoutButton.addTarget(self, action: #selector(didTapCheckoutButton), for: .touchUpInside)
    checkoutButton.isEnabled = false

    // MARK: Fetch the PaymentIntent client secret, Ephemeral Key secret, Customer ID, and publishable key
    var request = URLRequest(url: backendCheckoutUrl)
    request.httpMethod = "POST"
    let task = URLSession.shared.dataTask(with: request, completionHandler: { [weak self] (data, response, error) in
      guard let data = data,
            let json = try? JSONSerialization.jsonObject(with: data, options: []) as? [String : Any],
            let customerId = json["customer"] as? String,
            let customerEphemeralKeySecret = json["ephemeralKey"] as? String,
            let paymentIntentClientSecret = json["paymentIntent"] as? String,
            let publishableKey = json["publishableKey"] as? String,
            let self = self else {
        // Handle error
        return
      }

      STPAPIClient.shared.publishableKey = publishableKey
      // MARK: Create a PaymentSheet instance
      var configuration = PaymentSheet.Configuration()
      configuration.merchantDisplayName = "Example, Inc."
      configuration.customer = .init(id: customerId, ephemeralKeySecret: customerEphemeralKeySecret)
      // Set `allowsDelayedPaymentMethods` to true if your business handles
      // delayed notification payment methods like US bank accounts.
      configuration.allowsDelayedPaymentMethods = true
      self.paymentSheet = PaymentSheet(paymentIntentClientSecret: paymentIntentClientSecret, configuration: configuration)

      DispatchQueue.main.async {
        self.checkoutButton.isEnabled = true
      }
    })
    task.resume()
  }

}

@objc
func didTapCheckoutButton() {
  // MARK: Start the checkout process
  paymentSheet?.present(from: self) { paymentResult in
    // MARK: Handle the payment result
    switch paymentResult {
    case .completed:
      print("Your order is confirmed")
    case .canceled:
      print("Canceled!")
    case .failed(let error):
      print("Payment failed: \(error)")
    }
  }
}

Se PaymentSheetResult for .completed, informe ao usuário (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.

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"

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:

Quando estiver pronto para cobrar do cliente fora da sessão, use os IDs do cliente e do PaymentMethod para criar uma PaymentIntent. Para encontrar uma forma de pagamento para cobrar, liste as formas de pagamento associadas ao seu cliente. Este exemplo lista cartões, mas você pode listar qualquer tipo aceito.

curl -G https://api.stripe.com/v1/payment_methods \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -d customer=
{{CUSTOMER_ID}} \
  -d type=card

Quando tiver os IDs de Customer e PaymentMethod, crie um PaymentIntent com o valor e moeda do pagamento. Outros parâmetros que precisam ser definidos para o pagamento fora de sessão:

• Defina off_session como true para indicar que o cliente não está em seu fluxo de checkout durante uma tentativa de pagamento e não pode executar uma solicitação de autenticação feita por um parceiro, como emissor de cartão, banco ou outra instituição de pagamento. Se, durante o fluxo de checkout, um parceiro solicitar autenticação, a Stripe solicitará isenções usando informações do cliente de uma transação na sessão anterior. Se as condições de isenção não forem atendidas, o PaymentIntent pode gerar um erro.
• Defina o valor da propriedade confirm do PaymentIntent como true, para que a confirmação ocorra imediatamente após a criação do PaymentIntent.
• Defina payment_method com o ID do PaymentMethod e customer com o ID do Cliente.

curl https://api.stripe.com/v1/payment_intents \
  -u 
sk_test_BQokikJOvBiI2HlWgH4olfQ2
: \
  -d amount=1099 \
  -d currency=usd \
  # 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 \
  -d customer="{{CUSTOMER_ID}}" \
  -d payment_method="{{PAYMENT_METHOD_ID}}" \
  -d return_url="https://example.com/order/123/complete" \
  -d off_session=true \
  -d confirm=true