# Criar um marketplace

Crie contas conectadas usando a Accounts v1, recolha pagamentos de clientes e pague a vendedores ou prestadores de serviços no marketplace.

> #### Integrações da API Accounts v2
> 
> Este guia se aplica apenas às plataformas Connect existentes que utilizam a API Accounts v1. Se você é um novo usuário do Connect ou utiliza a API Accounts v2, consulte o [Guia do Marketplace v2](https://docs.stripe.com/connect/marketplace.md).

# Web

> This is a Web for when platform is web. View the full page at https://docs.stripe.com/connect/end-to-end-marketplace?platform=web.

Este guia explica como aceitar pagamentos e mover fundos para as contas bancárias dos seus provedores de serviços ou vendedores. Para fins de demonstração, criamos um marketplace de aluguel de casas que conecta proprietários a possíveis inquilinos. Também mostramos como aceitar pagamentos de inquilinos (clientes) e fazer repasses aos proprietários (os usuários da sua plataforma).

## Pré-requisitos

1. [Cadastre sua plataforma](https://dashboard.stripe.com/connect).
1. [Verifique e adicione os dados da empresa no Dashboard](https://dashboard.stripe.com/account/onboarding).
1. [Conclua seu perfil da plataforma](https://dashboard.stripe.com/connect/settings/profile).
1. [Personalize as configurações da sua marca](https://dashboard.stripe.com/settings/connect/stripe-dashboard/branding). Adicione um nome de empresa, ícone e cor da marca.

## Configurar a Stripe [Lado do servidor]

Instale as bibliotecas oficiais da Stripe para acessar a API Stripe no seu aplicativo:

#### Ruby

```bash
# Available as a gem
sudo gem install stripe
```

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

## Criar uma conta conectada

#### Accounts v2

Quando um vendedor ou provedor de serviços se cadastra na sua plataforma, crie uma [conta conectada](https://docs.stripe.com/api/v2/core/accounts.md) que o represente. A conta conectada permite que você recolha suas informações de identificação, aceite pagamentos para eles e transfira fundos para a conta bancária deles. Em nosso exemplo de aluguel de casas, a conta conectada representa o proprietário da casa.

#### Accounts v1

Quando um vendedor ou provedor de serviços se cadastra na sua plataforma, crie uma [conta conectada](https://docs.stripe.com/api/accounts.md) que o represente. A conta conectada permite que você recolha suas informações de identificação, aceite pagamentos para eles e transfira fundos para a conta bancária deles. Em nosso exemplo de aluguel de casas, a conta conectada representa o proprietário da casa.

### Crie uma conta conectada com informações pré-preenchidas

#### Accounts v2

Use a API `/v2/core/accounts` para [criar](https://docs.stripe.com/api/v2/core/accounts/create.md) uma conta conectada, especificando o [dashboard da conta conectada e as responsabilidades](https://docs.stripe.com/connect/accounts-v2/connected-account-configuration.md).

```curl
curl -X POST https://api.stripe.com/v2/core/accounts \
  -H "Authorization: Bearer <<YOUR_SECRET_KEY>>" \
  -H "Stripe-Version: 2026-01-28.clover" \
  --json '{
    "contact_email": "furever_contact@example.com",
    "display_name": "Furever",
    "defaults": {
        "responsibilities": {
            "fees_collector": "application",
            "losses_collector": "application"
        }
    },
    "dashboard": "express",
    "identity": {
        "business_details": {
            "registered_name": "Furever"
        },
        "country": "us",
        "entity_type": "company"
    },
    "configuration": {
        "merchant": {
            "capabilities": {
                "card_payments": {
                    "requested": true
                }
            }
        },
        "recipient": {
            "capabilities": {
                "stripe_balance": {
                    "stripe_transfers": {
                        "requested": true
                    }
                }
            }
        }
    },
    "include": [
        "configuration.merchant",
        "configuration.recipient",
        "identity",
        "requirements"
    ]
  }'
```

Se você já coletou dados de suas contas conectadas, pode usá-los para preencher o objeto `Account`. Você pode preencher quaisquer dados de conta, inclusive dados pessoais e comerciais, dados de contas externas e muito mais.

Após criar uma `Conta`, crie uma [Pessoa](https://docs.stripe.com/api/v2/core/persons/create.md) para representar a pessoa responsável por abrir a conta, definindo como verdadeiro `relationship.representative` e todas as informações da conta que você queira preencher previamente (por exemplo, o nome e sobrenome).

```curl
curl -X POST https://api.stripe.com/v2/core/accounts/{{ACCOUNT_ID}}/persons \
  -H "Authorization: Bearer <<YOUR_SECRET_KEY>>" \
  -H "Stripe-Version: 2026-04-22.preview" \
  --json '{
    "given_name": "Jenny",
    "surname": "Rosen",
    "email": "jenny.rosen@example.com",
    "relationship": {
        "representative": true
    }
  }'
```

O Connect Onboarding não solicita as informações pré-preenchidas. No entanto, ele solicita que o titular da conta confirme as informações pré-preenchidas antes de aceitar o [contrato de serviços do Connect](https://docs.stripe.com/connect/service-agreement-types.md).

Ao testar sua integração, preencha antecipadamente os dados da conta usando [dados de teste](https://docs.stripe.com/connect/testing.md).

### Criar um link da conta

Você pode criar um link de conta chamando a API [Account Links v2](https://docs.stripe.com/api/v2/core/account-links.md) com os seguintes parâmetros:

- `account`
- `refresh_url`
- `return_url`
- `type` = `account_onboarding`
- `configurations` = `recipient` e `merchant`

```curl
curl -X POST https://api.stripe.com/v2/core/account_links \
  -H "Authorization: Bearer <<YOUR_SECRET_KEY>>" \
  -H "Stripe-Version: 2025-08-27.preview" \
  --json '{
    "account": "{{CONNECTEDACCOUNT_ID}}",
    "use_case": {
        "type": "account_onboarding",
        "account_onboarding": {
            "configurations": [
                "recipient",
                "merchant"
            ],
            "refresh_url": "https://example.com/reauth",
            "return_url": "https://example.com/return"
        }
    }
  }'
```

### Redirecionar o usuário ao URL do link da conta

A resposta de criação do link da conta inclui um valor de `url`. Após autenticar o usuário no seu aplicativo, redirecione-o para essa URL para inseri-lo no fluxo. As URLs de link da conta são temporárias e de uso único, pois concedem acesso às informações pessoais do usuário da conta conectada. Se desejar preencher previamente as informações, deverá preencher antes de gerar o link da conta. Depois de criar o link da conta, não será possível ler nem gravar informações na conta conectada.

> Não envie URLs de links de conta por e-mail, SMS ou outra maneira para fora do aplicativo da sua plataforma. Em vez disso, forneça-os ao titular da conta autenticado dentro do seu aplicativo.

#### Item 1

#### Swift

```swift
import UIKit
import SafariServices

let BackendAPIBaseURL: String = "" // Set to the URL of your backend server

class ConnectOnboardViewController: UIViewController {

    // ...

    override func viewDidLoad() {
        super.viewDidLoad()

        let connectWithStripeButton = UIButton(type: .system)
        connectWithStripeButton.setTitle("Connect with Stripe", for: .normal)
        connectWithStripeButton.addTarget(self, action: #selector(didSelectConnectWithStripe), for: .touchUpInside)
        view.addSubview(connectWithStripeButton)

        // ...
    }

    @objc
    func didSelectConnectWithStripe() {
        if let url = URL(string: BackendAPIBaseURL)?.appendingPathComponent("onboard-user") {
          var request = URLRequest(url: url)
          request.httpMethod = "POST"
          let task = URLSession.shared.dataTask(with: request) { (data, response, error) in
              guard let data = data,
                  let json = try? JSONSerialization.jsonObject(with: data, options: []) as? [String : Any],
                  let accountURLString = json["url"] as? String,
                  let accountURL = URL(string: accountURLString) else {
                      // handle error
              }

              let safariViewController = SFSafariViewController(url: accountURL)
              safariViewController.delegate = self

              DispatchQueue.main.async {
                  self.present(safariViewController, animated: true, completion: nil)
              }
          }
        }
    }

    // ...
}

extension ConnectOnboardViewController: SFSafariViewControllerDelegate {
    func safariViewControllerDidFinish(_ controller: SFSafariViewController) {
        // the user may have closed the SFSafariViewController instance before a redirect
        // occurred. Sync with your backend to confirm the correct state
    }
}

```

#### Item 2

```xml
<?xml version="1.0" encoding="utf-8"?>
<androidx.constraintlayout.widget.ConstraintLayout
    xmlns:android="http://schemas.android.com/apk/res/android"
    xmlns:app="http://schemas.android.com/apk/res-auto"
    xmlns:tools="http://schemas.android.com/tools"
    android:layout_width="match_parent"
    android:layout_height="match_parent"
    tools:context=".activity.ConnectWithStripeActivity">

    <Button
        android:id="@+id/connect_with_stripe"
        android:text="Connect with Stripe"
        android:layout_height="wrap_content"
        android:layout_width="wrap_content"
        app:layout_constraintBottom_toBottomOf="parent"
        app:layout_constraintEnd_toEndOf="parent"
        app:layout_constraintStart_toStartOf="parent"
        app:layout_constraintTop_toTopOf="parent"
        style="?attr/materialButtonOutlinedStyle"
        />

</androidx.constraintlayout.widget.ConstraintLayout>
```

#### Kotlin

```kotlin
class ConnectWithStripeActivity : AppCompatActivity() {

    private val viewBinding: ActivityConnectWithStripeViewBinding by lazy {
        ActivityConnectWithStripeViewBinding.inflate(layoutInflater)
    }
    private val httpClient = OkHttpClient()

    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        setContentView(viewBinding.root)

        viewBinding.connectWithStripe.setOnClickListener {
            val weakActivity = WeakReference<Activity>(this)
            val request = Request.Builder()
                .url(BACKEND_URL + "onboard-user")
                .post("".toRequestBody())
                .build()
            httpClient.newCall(request)
                .enqueue(object: Callback {
                    override fun onFailure(call: Call, e: IOException) {
                        // Request failed
                    }
                    override fun onResponse(call: Call, response: Response) {
                        if (!response.isSuccessful) {
                            // Request failed
                        } else {
                            val responseData = response.body?.string()
                            val responseJson =
                                responseData?.let { JSONObject(it) } ?: JSONObject()
                            val url = responseJson.getString("url")

                            weakActivity.get()?.let {
                                val builder: CustomTabsIntent.Builder = CustomTabsIntent.Builder()
                                val customTabsIntent = builder.build()
                                customTabsIntent.launchUrl(it, Uri.parse(url))
                            }
                        }
                    }
                })
        }
    }

    internal companion object {
        internal const val BACKEND_URL = "https://example-backend-url.com/"
    }
}
```

#### Item 3

### Gerenciar o usuário que volta à plataforma

O Connect Onboarding exige que você passe tanto um `return_url` quanto um `refresh_url` para lidar com todos os casos em que o usuário da conta é redirecionado para a sua plataforma.

> Você pode usar HTTP para seu `return_url` e para o `refresh_url` enquanto estiver em um ambiente de teste (por exemplo, para testar com o localhost), mas modo de produção aceita apenas HTTPS. Você deve atualizar URLs de teste para URLs HTTPS antes do lançamento.

#### return_url

A Stripe emite um redirecionamento para essa URL quando o usuário da conta conectada conclui o fluxo de onboarding. Isso não significa que todas as informações tenham sido recolhidas ou que não haja requisitos pendentes na conta. Significa apenas que o fluxo foi inserido e encerrado corretamente.

Nenhum estado é transmitido por essa URL. Depois que um usuário for redirecionado para o seu `return_url`, verifique o estado dos requisitos na conta dele fazendo o seguinte:

- Ouça os Webhooks `v2.core.account[requirements].updated`.
- Chame a API [Accounts v2](https://docs.stripe.com/api/v2/core/accounts/retrieve.md) e inspecione o objeto retornado.

#### refresh_url

A Stripe redireciona seu usuário para o `refresh_url` nestes casos:

- O link expirou (alguns minutos se passaram desde a criação do link).
- O usuário já acessou o URL (atualizou a página ou clicou em Voltar ou Avançar no navegador).
- Sua plataforma não consegue mais acessar a conta.
- A conta foi recusada.

Configure sua página `refresh_url` para acionar um método em seu servidor para chamar [Account Links v2](https://docs.stripe.com/api/v2/core/account-links.md) novamente com os mesmos parâmetros e redirecionar o usuário para o novo link.

### Gerenciar usuários que não concluíram o onboarding

Um usuário redirecionado para o seu `return_url` pode não ter concluído o processo de onboarding. Use o endpoint `/v2/core/accounts` para recuperar a conta do usuário e verificar se [configuration.recipient.capabilities.stripe_balance.stripe_transfers.status](https://docs.stripe.com/api/v2/core/accounts/object.md#v2_account_object-configuration-recipient-capabilities-stripe_balance-stripe_transfers-status) está coo `active`. Se o status não estiver `active` e [configuration.destinatário.capabilities.stripe_balance.stripe_transfers.status_details.code](https://docs.stripe.com/api/v2/core/accounts/object.md#v2_account_object-configuration-recipient-capabilities-stripe_balance-stripe_transfers-status_details-code) for `requirements_past_due`, forneça prompts na IU para permitir que o usuário continue o onboarding por meio de um novo link de conta. Para outros códigos, trate-os conforme necessário.

#### Accounts v1

Use a API `/v1/accounts` para [criar](https://docs.stripe.com/api/accounts/create.md) uma conta conectada especificando as [propriedades da conta conectada](https://docs.stripe.com/connect/migrate-to-controller-properties.md) ou o tipo de conta.

```curl
curl https://api.stripe.com/v1/accounts \
  -u "<<YOUR_SECRET_KEY>>:" \
  -d "controller[losses][payments]=application" \
  -d "controller[fees][payer]=application" \
  -d "controller[stripe_dashboard][type]=express"
```

Se você já coletou dados de suas contas conectadas, pode usá-los para preencher o objeto `Account`. Você pode preencher quaisquer dados de conta, inclusive dados pessoais e comerciais, dados de contas externas e muito mais.

Depois de criar uma `Account`, crie uma [Pessoa](https://docs.stripe.com/api/persons/create.md) para representar a pessoa responsável por abrir a conta, com `relationship.representative` definido como verdadeiro e informações da conta que você queira preencher previamente (por exemplo, o nome e sobrenome).

```curl
curl https://api.stripe.com/v1/accounts/{{ACCOUNT_ID}}/persons \
  -u "<<YOUR_SECRET_KEY>>:" \
  -d first_name=Jenny \
  -d last_name=Rosen \
  -d "relationship[representative]=true"
```

O Connect Onboarding não solicita as informações pré-preenchidas. No entanto, ele solicita que o titular da conta confirme as informações pré-preenchidas antes de aceitar o [contrato de serviços do Connect](https://docs.stripe.com/connect/service-agreement-types.md).

Ao testar sua integração, preencha antecipadamente os dados da conta usando [dados de teste](https://docs.stripe.com/connect/testing.md).

### Criar um link da conta

Você pode criar um link de conta chamando a API [Account Links v1](https://docs.stripe.com/api/account_links.md) com os seguintes parâmetros:

- `account`
- `refresh_url`
- `return_url`
- `type` = `account_onboarding`

```curl
curl https://api.stripe.com/v1/account_links \
  -u "<<YOUR_SECRET_KEY>>:" \
  -d "account={{CONNECTEDACCOUNT_ID}}" \
  --data-urlencode "refresh_url=https://example.com/reauth" \
  --data-urlencode "return_url=https://example.com/return" \
  -d type=account_onboarding
```

### Redirecionar o usuário ao URL do link da conta

A resposta da criação do link da conta inclui um valor de `url`. Após autenticar o usuário no seu aplicativo, redirecione-o para esta URL para inseri-lo no fluxo. As URLs de links de conta da [API Account Links v1](https://docs.stripe.com/api/account_links.md) são temporárias e de uso único, pois concedem acesso às informações pessoais do usuário da conta conectada. Autentique o usuário no seu aplicativo antes de redirecioná-lo para esta URL. Se desejar preencher previamente as informações, deverá preencher antes de gerar o link da conta. Depois de criar o link da conta, não será possível ler nem gravar informações da conta conectada.

> Não envie URLs de links de conta por e-mail, SMS ou outra maneira para fora do aplicativo da sua plataforma. Em vez disso, forneça-os ao titular da conta autenticado dentro do seu aplicativo.

#### Item 1

#### Swift

```swift
import UIKit
import SafariServices

let BackendAPIBaseURL: String = "" // Set to the URL of your backend server

class ConnectOnboardViewController: UIViewController {

    // ...

    override func viewDidLoad() {
        super.viewDidLoad()

        let connectWithStripeButton = UIButton(type: .system)
        connectWithStripeButton.setTitle("Connect with Stripe", for: .normal)
        connectWithStripeButton.addTarget(self, action: #selector(didSelectConnectWithStripe), for: .touchUpInside)
        view.addSubview(connectWithStripeButton)

        // ...
    }

    @objc
    func didSelectConnectWithStripe() {
        if let url = URL(string: BackendAPIBaseURL)?.appendingPathComponent("onboard-user") {
          var request = URLRequest(url: url)
          request.httpMethod = "POST"
          let task = URLSession.shared.dataTask(with: request) { (data, response, error) in
              guard let data = data,
                  let json = try? JSONSerialization.jsonObject(with: data, options: []) as? [String : Any],
                  let accountURLString = json["url"] as? String,
                  let accountURL = URL(string: accountURLString) else {
                      // handle error
              }

              let safariViewController = SFSafariViewController(url: accountURL)
              safariViewController.delegate = self

              DispatchQueue.main.async {
                  self.present(safariViewController, animated: true, completion: nil)
              }
          }
        }
    }

    // ...
}

extension ConnectOnboardViewController: SFSafariViewControllerDelegate {
    func safariViewControllerDidFinish(_ controller: SFSafariViewController) {
        // the user may have closed the SFSafariViewController instance before a redirect
        // occurred. Sync with your backend to confirm the correct state
    }
}

```

#### Item 2

```xml
<?xml version="1.0" encoding="utf-8"?>
<androidx.constraintlayout.widget.ConstraintLayout
    xmlns:android="http://schemas.android.com/apk/res/android"
    xmlns:app="http://schemas.android.com/apk/res-auto"
    xmlns:tools="http://schemas.android.com/tools"
    android:layout_width="match_parent"
    android:layout_height="match_parent"
    tools:context=".activity.ConnectWithStripeActivity">

    <Button
        android:id="@+id/connect_with_stripe"
        android:text="Connect with Stripe"
        android:layout_height="wrap_content"
        android:layout_width="wrap_content"
        app:layout_constraintBottom_toBottomOf="parent"
        app:layout_constraintEnd_toEndOf="parent"
        app:layout_constraintStart_toStartOf="parent"
        app:layout_constraintTop_toTopOf="parent"
        style="?attr/materialButtonOutlinedStyle"
        />

</androidx.constraintlayout.widget.ConstraintLayout>
```

#### Kotlin

```kotlin
class ConnectWithStripeActivity : AppCompatActivity() {

    private val viewBinding: ActivityConnectWithStripeViewBinding by lazy {
        ActivityConnectWithStripeViewBinding.inflate(layoutInflater)
    }
    private val httpClient = OkHttpClient()

    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        setContentView(viewBinding.root)

        viewBinding.connectWithStripe.setOnClickListener {
            val weakActivity = WeakReference<Activity>(this)
            val request = Request.Builder()
                .url(BACKEND_URL + "onboard-user")
                .post("".toRequestBody())
                .build()
            httpClient.newCall(request)
                .enqueue(object: Callback {
                    override fun onFailure(call: Call, e: IOException) {
                        // Request failed
                    }
                    override fun onResponse(call: Call, response: Response) {
                        if (!response.isSuccessful) {
                            // Request failed
                        } else {
                            val responseData = response.body?.string()
                            val responseJson =
                                responseData?.let { JSONObject(it) } ?: JSONObject()
                            val url = responseJson.getString("url")

                            weakActivity.get()?.let {
                                val builder: CustomTabsIntent.Builder = CustomTabsIntent.Builder()
                                val customTabsIntent = builder.build()
                                customTabsIntent.launchUrl(it, Uri.parse(url))
                            }
                        }
                    }
                })
        }
    }

    internal companion object {
        internal const val BACKEND_URL = "https://example-backend-url.com/"
    }
}
```

### Gerenciar o usuário que volta à plataforma

O Connect Onboarding exige que você passe um `return_url` e `refresh_url` para gerenciar todos os casos em que o usuário é redirecionado à sua plataforma. É importante implementá-los corretamente para proporcionar a melhor experiência ao usuário.

> Você pode usar HTTP para seu `return_url` e para o `refresh_url` enquanto estiver em um ambiente de teste (por exemplo, para testar com o localhost), mas modo de produção aceita apenas HTTPS. Você deve atualizar URLs de teste para URLs HTTPS antes do lançamento.

#### return_url

A Stripe emite um redirecionamento para essa URL quando o usuário da conta conectada conclui o fluxo de onboarding. Isso não significa que todas as informações tenham sido recolhidas ou que não haja requisitos pendentes na conta. Significa apenas que o fluxo foi inserido e encerrado corretamente.

Nenhum estado é passado por este URL. Após o redirecionamento de um usuário para o `return_url` , verifique o estado do parâmetro `details_submitted` na conta dele realizando uma das seguintes ações:

- Ouça os Webhooks `account.updated`
- Chame a API [Accounts v1](https://docs.stripe.com/api/accounts.md) e inspecione o objeto retornado

#### refresh_url

A Stripe redireciona seu usuário para o `refresh_url` nestes casos:

- O link expirou (alguns minutos se passaram desde a criação do link).
- O usuário já acessou o URL (atualizou a página ou clicou em Voltar ou Avançar no navegador).
- Sua plataforma não consegue mais acessar a conta.
- A conta foi recusada.

Configure sua página `refresh_url` para acionar um método em seu servidor para chamar [Account Links v1](https://docs.stripe.com/api/account_links.md) novamente com os mesmos parâmetros e redirecionar o usuário para o novo link.

### Gerenciar usuários que não concluíram o onboarding

Um usuário que é redirecionado para seu `return_url` pode não ter concluído o processo de onboarding. Use o endpoint `/v1/accounts` para recuperar a conta do usuário e verificar se `charges_enabled`. Se a conta não estiver totalmente integrada, forneça prompts de IU para permitir que o usuário continue fazendo onboarding por meio de um novo link de conta. Você pode determinar se eles concluíram o onboarding verificando o estado do parâmetro `details_submitted` na conta deles.

## Habilitar formas de pagamento

Veja as [configurações de formas de pagamento](https://dashboard.stripe.com/settings/payment_methods) e ative as que pretende aceitar. Pagamentos com cartão, Google Pay e Apple Pay ficam ativados por padrão, mas você pode ativar e desativar as formas de pagamento conforme a necessidade.

Antes da exibição das formas de pagamento, a Stripe avalia a moeda, as restrições e outros parâmetros dessas formas de pagamento para criar a lista das que são aceitas. Priorizamos as que aumentam a conversão e são mais relevantes para a moeda e a localização do cliente. As formas de pagamento de menor prioridade são ocultas em um menu de estouro.

## Aceitar um pagamento

Use o [Stripe Checkout](https://stripe.com/payments/checkout) para aceitar pagamentos. O Checkout aceita várias formas de pagamento e mostra automaticamente as mais relevantes ao cliente. Você pode aceitar pagamentos com o Checkout usando uma página hospedada pela Stripe ou adicionar uma forma de pagamento incorporável pré-configurada diretamente em seu site. Também é possível criar um fluxo personalizado (usando o Payment Element) para aceitar várias formas de pagamento com uma única integração de front-end.

#### Página hospedada pela Stripe

### Crie uma Sessão do Checkout (Cliente e servidor)

Uma Sessão do Checkout controla o que seu cliente vê na página de pagamentos hospedada pela Stripe, como itens de linha, valor, moeda e formas de pagamento aceitas.

Adicione um botão de checkout ao seu site para chamar um endpoint do lado do servidor e criar uma Sessão do Checkout.

```html
<html>
  <head>
    <title>Checkout</title>
  </head>
  <body>
    <form action="/create-checkout-session" method="POST">
      <button type="submit">Checkout</button>
    </form>
  </body>
</html>
```

No servidor, faça a chamada a seguir para a API da Stripe. Depois de criar uma Sessão do Checkout, redirecione o cliente para o [URL](https://docs.stripe.com/api/checkout/sessions/object.md#checkout_session_object-url) retornado na resposta.

```curl
curl https://api.stripe.com/v1/checkout/sessions \
  -u "<<YOUR_SECRET_KEY>>:" \
  -d mode=payment \
  -d "line_items[0][price]={{PRICE_ID}}" \
  -d "line_items[0][quantity]=1" \
  -d "payment_intent_data[application_fee_amount]=123" \
  -d "payment_intent_data[transfer_data][destination]={{CONNECTEDACCOUNT_ID}}" \
  --data-urlencode "success_url=https://example.com/success"
```

- `line_items` - este argumento representa os itens que o cliente está comprando e que serão exibidos na interface do usuário hospedada pela Stripe.
- `success_url` - este argumento redireciona um usuário após a conclusão de um pagamento.
- `payment_intent_data[application_fee_amount]` - este argumento especifica o valor planejado pela sua plataforma para retirar da transação. O valor total da cobrança é imediatamente transferido da plataforma para a conta conectada que é especificada por `transfer_data[destination]` após a captura da cobrança. O `application_fee_amount` é transferido de volta para a plataforma, e a tarifa da Stripe é deduzida do valor da plataforma.
- `payment_intent_data[transfer_data][destination]` - este argumento indica que é uma [cobrança de destino](https://docs.stripe.com/connect/destination-charges.md). Uma cobrança de destino significa que a cobrança é processada na plataforma e, em seguida, os fundos são imediatamente e automaticamente transferidos para o saldo pendente da conta conectada. Para o nosso exemplo de aluguel residencial, queremos construir uma experiência na qual o cliente pague por meio da plataforma, e o proprietário receba o pagamento pela plataforma.
![](https://b.stripecdn.com/docs-statics-srv/assets/application_fee_amount.837aa2339469b3c1a4319672971c1367.svg)

O Checkout usa as configurações de marca da sua conta de plataforma para cobranças de destino. Para obter mais informações, consulte [Personalizar a marca](https://docs.stripe.com/connect/destination-charges.md?platform=web&ui=stripe-hosted#branding).

Esta Sessão cria uma cobrança de destino. Se você precisar controlar o cronograma de transferências ou precisar transferir fundos de um único pagamento para várias partes, use [cobranças e transferências separadas](https://docs.stripe.com/connect/separate-charges-and-transfers.md).

### Gerencie eventos pós-pagamento (Server-side)

A Stripe envia um evento [checkout.session.completed](https://docs.stripe.com/api/events/types.md#event_types-checkout.session.completed) quando o pagamento é concluído. [Use um webhook para receber esses eventos](https://docs.stripe.com/webhooks/quickstart.md) e executar ações, como enviar um e-mail de confirmação de pedido ao cliente, registrar a venda em um banco de dados ou iniciar um fluxo de entrega.

Escute esses eventos em vez de aguardar um retorno de chamada do cliente. No cliente, o consumidor poderia fechar a janela do navegador ou sair do aplicativo antes da execução do retorno de chamada. Algumas formas de pagamento também demoram de 2 a 14 dias para a confirmação do pagamento. Configurar sua integração para escutar eventos assíncronos é o que permite a você aceitar diferentes tipos de [formas de pagamento](https://stripe.com/payments/payment-methods-guide) com uma única integração.

Além de gerenciar o evento `checkout.session.completed`, recomendamos gerenciar dois outros eventos ao coletar pagamentos com o Checkout:

| Evento                                                                                                                                       | Descrição                                                          | Próximas etapas                                                                     |
| -------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------ | ----------------------------------------------------------------------------------- |
| [checkout.session.completed](https://docs.stripe.com/api/events/types.md#event_types-checkout.session.completed)                             | O cliente autorizou o pagamento enviando o formulário do Checkout. | Aguarde a confirmação ou falha do pagamento.                                        |
| [checkout.session.async_payment_succeeded](https://docs.stripe.com/api/events/types.md#event_types-checkout.session.async_payment_succeeded) | O pagamento do cliente foi confirmado.                             | Execute o pedido de mercadorias ou serviços.                                        |
| [checkout.session.async_payment_failed](https://docs.stripe.com/api/events/types.md#event_types-checkout.session.async_payment_failed)       | O pagamento foi recusado ou houve outro erro.                      | Entre em contato com o cliente por e-mail e solicite que seja feito um novo pedido. |

Todos esses eventos incluem o objeto [Checkout Session](https://docs.stripe.com/api/checkout/sessions.md). Após o êxito do pagamento, o status subjacente do *PaymentIntent* (The Payment Intents API tracks the lifecycle of a customer checkout flow and triggers additional authentication steps when required by regulatory mandates, custom Radar fraud rules, or redirect-based payment methods) passa de `processing` para `succeeded`.

#### Formulário integrado

### Crie uma Sessão do Checkout (Server-side)

A Sessão do Checkout controla o que seu cliente vê no formulário de pagamento integrado, como itens de linha, valor, moeda e formas de pagamento aceitas.

No seu servidor, faça a seguinte chamada para a API da Stripe.

```curl
curl https://api.stripe.com/v1/checkout/sessions \
  -u "<<YOUR_SECRET_KEY>>:" \
  -d mode=payment \
  -d "line_items[0][price]={{PRICE_ID}}" \
  -d "line_items[0][quantity]=1" \
  -d "payment_intent_data[application_fee_amount]=123" \
  -d "payment_intent_data[transfer_data][destination]={{CONNECTEDACCOUNT_ID}}" \
  -d ui_mode=embedded_page \
  --data-urlencode "return_url=https://example.com/checkout/return?session_id={CHECKOUT_SESSION_ID}"
```

- `line_items` - os itens que o cliente está comprando. Exibido na interface do usuário hospedada pela Stripe.
- `return_url` - este argumento redireciona um usuário após a conclusão de uma tentativa de pagamento.
- `payment_intent_data[application_fee_amount]` - este argumento especifica o valor planejado pela sua plataforma para retirar da transação. O valor total da cobrança é imediatamente transferido da plataforma para a conta conectada que é especificada por `transfer_data[destination]` após a captura da cobrança. O `application_fee_amount` é transferido de volta para a plataforma, e a tarifa da Stripe é deduzida do valor da plataforma.
- `payment_intent_data[transfer_data][destination]` - indica que é uma [cobrança de destino](https://docs.stripe.com/connect/destination-charges.md), ou seja, que a cobrança é processada na plataforma. Em seguida, os fundos são imediatamente e automaticamente transferidos para o saldo pendente da conta conectada. No exemplo de aluguel residencial, se o cliente pagar por meio da plataforma, o proprietário recebe o pagamento pela plataforma.

### Montar checkout (Client-side)

#### HTML + JS

O Checkout está disponível no [Stripe.js](https://docs.stripe.com/js.md). Inclua o script Stripe.js na página, adicionando-o ao cabeçalho do arquivo HTML. Crie um nó DOM vazio (contêiner) para usar na montagem.

```html
<head>
  <script src="https://js.stripe.com/dahlia/stripe.js"></script>
</head>
<body>
  <div id="checkout">
    <!-- Checkout will insert the payment form here -->
  </div>
</body>
```

Inicialize o Stripe.js com sua chave de API publicável.

Crie uma função assíncrona `fetchClientSecret` que faz uma solicitação ao seu servidor para criar a sessão do Checkout e recuperar o segredo do cliente. Passe essa função para `options` quando criar a instância do Checkout:

```javascript
// Initialize Stripe.js
const stripe = Stripe('<<YOUR_PUBLISHABLE_KEY>>');

initialize();

// Fetch Checkout Session and retrieve the client secret
async function initialize() {
  const fetchClientSecret = async () => {
    const response = await fetch("/create-checkout-session", {
      method: "POST",
    });
    const { clientSecret } = await response.json();
    return clientSecret;
  };

  // Initialize Checkout
  const checkout = await stripe.createEmbeddedCheckoutPage({
    fetchClientSecret,
  });

  // Mount Checkout
  checkout.mount('#checkout');
}
```

#### React

Instale as bibliotecas Connect.js e React Connect.js a partir do [registro público do npm](https://www.npmjs.com/package/@stripe/react-connect-js).

```bash
npm install --save @stripe/connect-js @stripe/react-connect-js
```

Para usar o componente Embedded Checkout, crie um `EmbeddedCheckoutProvider`. Chame `loadStripe` com sua chave de API publicável e passe a `Promise` retornada para o provedor.

Crie uma função assíncrona `fetchClientSecret` que faz uma solicitação ao seu servidor para criar a sessão do Checkout e recuperar o segredo do cliente. Passe essa função para a propriedade `options` aceita pelo provedor.

```jsx
import * as React from 'react';
import {loadStripe} from '@stripe/stripe-js';
import {
  EmbeddedCheckoutProvider,
  EmbeddedCheckout
} from '@stripe/react-stripe-js';

// Make sure to call `loadStripe` outside of a component’s render to avoid
// recreating the `Stripe` object on every render.
const stripePromise = loadStripe('pk_test_123');

const App = ({fetchClientSecret}) => {
  const options = {fetchClientSecret};

  return (
    <EmbeddedCheckoutProvider
      stripe={stripePromise}
      options={options}
    >
      <EmbeddedCheckout />
    </EmbeddedCheckoutProvider>
  )
}
```

O Checkout é renderizado em um iframe que envia dados de pagamento com segurança à Stripe por uma conexão HTTPS. Evite colocar o Checkout dentro de outro iframe porque algumas formas de pagamento exigem o redirecionamento para outra página para confirmação do pagamento.
![](https://b.stripecdn.com/docs-statics-srv/assets/application_fee_amount.837aa2339469b3c1a4319672971c1367.svg)

O Checkout usa as configurações de marca da sua conta de plataforma para cobranças de destino. Para obter mais informações, consulte [Personalizar a marca](https://docs.stripe.com/connect/destination-charges.md?platform=web&ui=stripe-hosted#branding).

Esta Sessão cria uma cobrança de destino. Se você precisar controlar o cronograma de transferências ou precisar transferir fundos de um único pagamento para várias partes, use [cobranças e transferências separadas](https://docs.stripe.com/connect/separate-charges-and-transfers.md).

### Gerencie eventos pós-pagamento (Server-side)

A Stripe envia um evento [checkout.session.completed](https://docs.stripe.com/api/events/types.md#event_types-checkout.session.completed) quando o pagamento é concluído. [Use um webhook para receber esses eventos](https://docs.stripe.com/webhooks/quickstart.md) e executar ações, como enviar um e-mail de confirmação de pedido ao cliente, registrar a venda em um banco de dados ou iniciar um fluxo de entrega.

Escute esses eventos em vez de aguardar um retorno de chamada do cliente. No cliente, o consumidor poderia fechar a janela do navegador ou sair do aplicativo antes da execução do retorno de chamada. Algumas formas de pagamento também demoram de 2 a 14 dias para a confirmação do pagamento. Configurar sua integração para escutar eventos assíncronos é o que permite a você aceitar diferentes tipos de [formas de pagamento](https://stripe.com/payments/payment-methods-guide) com uma única integração.

Além de gerenciar o evento `checkout.session.completed`, recomendamos gerenciar dois outros eventos ao coletar pagamentos com o Checkout:

| Evento                                                                                                                                       | Descrição                                                          | Próximas etapas                                                                     |
| -------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------ | ----------------------------------------------------------------------------------- |
| [checkout.session.completed](https://docs.stripe.com/api/events/types.md#event_types-checkout.session.completed)                             | O cliente autorizou o pagamento enviando o formulário do Checkout. | Aguarde a confirmação ou falha do pagamento.                                        |
| [checkout.session.async_payment_succeeded](https://docs.stripe.com/api/events/types.md#event_types-checkout.session.async_payment_succeeded) | O pagamento do cliente foi confirmado.                             | Execute o pedido de mercadorias ou serviços.                                        |
| [checkout.session.async_payment_failed](https://docs.stripe.com/api/events/types.md#event_types-checkout.session.async_payment_failed)       | O pagamento foi recusado ou houve outro erro.                      | Entre em contato com o cliente por e-mail e solicite que seja feito um novo pedido. |

Todos esses eventos incluem o objeto [Checkout Session](https://docs.stripe.com/api/checkout/sessions.md). Após o êxito do pagamento, o status subjacente do *PaymentIntent* (The Payment Intents API tracks the lifecycle of a customer checkout flow and triggers additional authentication steps when required by regulatory mandates, custom Radar fraud rules, or redirect-based payment methods) passa de `processing` para `succeeded`.

#### Fluxo personalizado

### Crie um PaymentIntent (Server-side)

A Stripe usa um objeto [PaymentIntent](https://docs.stripe.com/api/payment_intents.md) 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.

> Se quiser renderizar o Payment Element antes de criar um PaymentIntent, consulte [Coletar detalhes do pagamento antes de criar um Intent](https://docs.stripe.com/payments/accept-a-payment-deferred.md?type=payment).
![Um diagrama de visão geral de todo o fluxo de pagamento](https://b.stripecdn.com/docs-statics-srv/assets/accept-a-payment-payment-element.5cf6795a02f864923f9953611493d735.svg)

As formas de pagamento mostradas aos clientes durante o processo de checkout também estão incluídas no PaymentIntent. Você pode deixar que a Stripe obtenha automaticamente as formas de pagamento das configurações do Dashboard ou listá-las manualmente.

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. A Stripe avalia a moeda, as restrições e outros parâmetros dessas formas de pagamento para criar a lista das que são aceitas. Priorizamos as que aumentam a conversão e são mais relevantes para a moeda e a localização do cliente. As formas de pagamento de menor prioridade são ocultas em um menu de navegação.

#### Gerenciar formas de pagamento no Dashboard

Crie um PaymentIntent no seu servidor com um valor e uma moeda habilitados. Na versão mais recente da API, especificar o parâmetro `automatic_payment_methods` é opcional porque a Stripe habilita sua funcionalidade por padrão. Você pode gerenciar formas de pagamento no [Dashboard](https://dashboard.stripe.com/settings/payment_methods). A Stripe processa a devolução de formas de pagamento qualificadas com base em fatores como valor, moeda e fluxo de pagamento da transação. O PaymentIntent é criado para aceitar as formas de pagamento que você configura no Dashboard, quando aplicável. Sempre decida o valor a ser cobrado no lado do servidor (um ambiente confiável), e não no lado do cliente. Isso impede que clientes maliciosos possam definir os próprios preços.

```curl
curl https://api.stripe.com/v1/payment_intents \
  -u "<<YOUR_SECRET_KEY>>:" \
  -d amount=1099 \
  -d currency=eur \
  -d "automatic_payment_methods[enabled]=true" \
  -d application_fee_amount=123 \
  -d "transfer_data[destination]={{CONNECTEDACCOUNT_ID}}"
```

#### Listar manualmente as formas de pagamento

Crie um PaymentIntent no seu servidor com valor, moeda e uma lista de tipos de formas de pagamento. Sempre decida quanto deseja cobrar no lado do servidor, um ambiente seguro, e não no lado do cliente, para evitar que clientes mal-intencionados escolham os próprios preços.

```curl
curl https://api.stripe.com/v1/payment_intents \
  -u "<<YOUR_SECRET_KEY>>:" \
  -H "Stripe-Account: {{CONNECTEDACCOUNT_ID}}" \
  -d amount=1099 \
  -d currency=eur \
  -d "payment_method_types[]=bancontact" \
  -d "payment_method_types[]=card" \
  -d "payment_method_types[]=eps" \
  -d "payment_method_types[]=ideal" \
  -d "payment_method_types[]=p24" \
  -d "payment_method_types[]=sepa_debit" \
  -d "payment_method_types[]=sofort" \
  -d application_fee_amount=123
```

Escolha a moeda de acordo com as formas de pagamento que você pretende aceitar. Algumas formas de pagamento aceitam várias moedas e países. Este guia usa Bancontact, cartões de crédito, EPS, iDEAL, Przelewy24 e débito automático SEPA e Sofort.

> A forma de pagamento precisa aceitar a moeda passada no PaymentIntent. Além disso, sua empresa precisa estar estabelecida em um dos países aceitos pela forma de pagamento. Consulte [Opções de integração de formas de pagamento](https://docs.stripe.com/payments/payment-methods/integration-options.md) para obter mais detalhes sobre o que é aceito.

### Recuperar o segredo do cliente

O PaymentIntent inclui um *segredo do cliente* (The client secret is a unique key returned from Stripe as part of a PaymentIntent. This key lets the client access important fields from the PaymentIntent (status, amount, currency) while hiding sensitive ones (metadata, customer)) que o lado do cliente usa para concluir com segurança o processo de pagamento. Você pode usar abordagens diferentes para enviar a senha do cliente ao lado do cliente.

#### Aplicativo de página única

Recupere o segredo do cliente de um endpoint do servidor usando a função `fetch` do navegador. Essa abordagem é melhor quando o lado do cliente é um aplicativo com uma única página, principalmente se criado com uma estrutura de front-end moderna como o React. Crie o endpoint do servidor que envia o segredo do cliente:

#### Ruby

```ruby
get '/secret' do
  intent = # ... Create or retrieve the PaymentIntent
  {client_secret: intent.client_secret}.to_json
end
```

Em seguida, obtenha o segredo do cliente com JavaScript no lado do cliente:

```javascript
(async () => {
  const response = await fetch('/secret');
  const {client_secret: clientSecret} = await response.json();
  // Render the form using the clientSecret
})();
```

#### Renderização do lado do servidor

Passe o segredo do cliente do servidor ao cliente. Essa abordagem funciona melhor quando o aplicativo gera conteúdo estático no servidor antes de enviá-lo ao navegador.

Adicione o [client_secret](https://docs.stripe.com/api/payment_intents/object.md#payment_intent_object-client_secret) ao formulário de checkout. No código do lado do servidor, recupere o segredo do cliente do PaymentIntent:

#### Ruby

```erb
<form id="payment-form" data-secret="<%= @intent.client_secret %>">
  <div id="payment-element">
    <!-- placeholder for Elements -->
  </div>
  <button id="submit">Submit</button>
</form>
```

```ruby
get '/checkout' do
  @intent = # ... Fetch or create the PaymentIntent
  erb :checkout
end
```

### Colete os dados de pagamento (Client-side)

Colete dados de pagamento no cliente com o [Payment Element](https://docs.stripe.com/payments/payment-element.md). O Payment Element é um componente de IU que simplifica a coleta de dados de pagamento para diversas formas de pagamento.

O Payment Element contém um iframe que envia dados de pagamento com segurança à Stripe por uma conexão HTTPS. Evite colocar o Payment Element dentro de outro iframe porque algumas formas de pagamento exigem o redirecionamento para outra página para confirmação do pagamento.

Se você optar por usar um iframe e quiser aceitar Apple Pay ou Google Pay, o iframe deve ter o atributo [permitir](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/iframe#attr-allowpaymentrequest) definido como igual a `"pagamento *"`.

O endereço da página de Checkout deve começar com `https://` rather em vez de `http://` for para que sua integração funcione corretamente. Você pode testar sua integração sem usar HTTPS, mas lembre-se de [habilitá-lo](https://docs.stripe.com/security/guide.md#tls) quando estiver pronto para aceitar pagamentos em tempo real.

#### HTML + JS

### Configurar o Stripe.js

O Payment Element está automaticamente disponível como um recurso do Stripe.js. Inclua o script Stripe.js em sua página de checkout adicionando-o ao `head` do arquivo HTML. Sempre carregue Stripe.js diretamente de js.stripe.com para manter a conformidade com PCI. Não inclua o script em um pacote nem hospede pessoalmente uma cópia dele.

```html
<head>
  <title>Checkout</title>
  <script src="https://js.stripe.com/dahlia/stripe.js"></script>
</head>
```

Crie uma instância de Stripe com o seguinte JavaScript em sua página de checkout:

```javascript
// Set your publishable key: remember to change this to your live publishable key in production
// See your keys here: https://dashboard.stripe.com/apikeys
const stripe = Stripe('<<YOUR_PUBLISHABLE_KEY>>');
```

### Adicione o Element Pagamento à sua página de pagamentos

O Payment Element precisa de um lugar para residir na sua página de pagamentos. Crie um node DOM vazio (contêiner) com um ID único no seu formulário de pagamento:

```html
<form id="payment-form">
  <div id="payment-element">
    <!-- Elements will create form elements here -->
  </div>
  <button id="submit">Submit</button>
  <div id="error-message">
    <!-- Display error message to your customers here -->
  </div>
</form>
```

Quando o formulário anterior for carregado, crie uma instância do Payment Element e monte-a no nó DOM do contêiner. Passe o [segredo do cliente](https://docs.stripe.com/api/payment_intents/object.md#payment_intent_object-client_secret) da etapa anterior em `options` quando criar a instância do [Elements](https://docs.stripe.com/js/elements_object/create):

Administre cuidadosamente o segredo do cliente, pois ele pode finalizar a cobrança. Não registre em log, incorpore em URLs nem exponha esse segredo a ninguém, exceto para o próprio cliente.

```javascript
const options = {
  clientSecret: '{{CLIENT_SECRET}}',
  // Fully customizable with appearance API.
  appearance: {/*...*/},
};

// Set up Stripe.js and Elements to use in checkout form, passing the client secret obtained in a previous stepconst elements = stripe.elements(options);

// Create and mount the Payment Element
const paymentElementOptions = { layout: 'accordion'};
const paymentElement = elements.create('payment', paymentElementOptions);
paymentElement.mount('#payment-element');

```

#### React

### Configurar o Stripe.js

Instale o [React Stripe.js](https://www.npmjs.com/package/@stripe/react-stripe-js) e o [carregador Stripe.js](https://www.npmjs.com/package/@stripe/stripe-js) do registro público npm:

```bash
npm install --save @stripe/react-stripe-js @stripe/stripe-js
```

### Adicione e configure o provedor do Elements à sua página de pagamento

Para usar o componente Payment Element, encapsule o componente da página de checkout em um [provedor do Elements](https://docs.stripe.com/sdks/stripejs-react.md#elements-provider). Chame `loadStripe` com sua chave publicável e passe a `Promise` retornada para o provedor `Elements`. Além disso, passe o [segredo do cliente](https://docs.stripe.com/api/payment_intents/object.md#payment_intent_object-client_secret) da etapa anterior como `options` ao fornecedor do `Elements`.

```jsx
import React from 'react';
import ReactDOM from 'react-dom';
import {Elements} from '@stripe/react-stripe-js';
import {loadStripe} from '@stripe/stripe-js';

import CheckoutForm from './CheckoutForm';

// Make sure to call `loadStripe` outside of a component’s render to avoid
// recreating the `Stripe` object on every render.
const stripePromise = loadStripe('<<YOUR_PUBLISHABLE_KEY>>');

function App() {
  const options = {
    // passing the client secret obtained in step 3
    clientSecret: '{{CLIENT_SECRET}}',
    // Fully customizable with appearance API.
    appearance: {/*...*/},
  };

  return (
    <Elements stripe={stripePromise} options={options}>
      <CheckoutForm />
    </Elements>
  );
};

ReactDOM.render(<App />, document.getElementById('root'));
```

### Adicione o componente do Element Pagamento

Use o componente `PaymentElement` para criar seu formulário:

```jsx
import React from 'react';
import {PaymentElement} from '@stripe/react-stripe-js';

const CheckoutForm = () => {
  return (
    <form><PaymentElement />
      <button>Submit</button>
    </form>
  );
};

export default CheckoutForm;
```

O Stripe Elements é uma coleção de componentes drop-in de IU. Para personalizar ainda mais o formulário ou coletar outros dados do cliente, consulte a [documentação do Elements](https://docs.stripe.com/payments/elements.md).

O Payment Element renderiza um formulário dinâmico que permite ao cliente escolher uma forma de pagamento. Para cada forma de pagamento, o formulário solicita automaticamente que o cliente preencha todos os dados de pagamento necessários.

### Personalizar a aparência

Personalize o Payment Element para corresponder ao design do seu site, passando o [objeto appearance](https://docs.stripe.com/js/elements_object/create#stripe_elements-options-appearance) para `options` ao criar o provedor do `Elements`.

### Solicitar endereços

Por padrão, o Payment Element só recolhe os detalhes necessários do endereço de faturamento. Alguns comportamentos, como [calcular impostos](https://docs.stripe.com/api/tax/calculations/create.md) ou inserir detalhes de entrega, exigem o endereço completo do cliente. Você pode:

- Use o [Address Element](https://docs.stripe.com/elements/address-element.md) para aproveitar os recursos de autocompletar e traduzir para recolher o endereço completo do cliente. Isso ajuda a garantir um cálculo tributário mais preciso.
- Obtenha os detalhes do endereço usando seu próprio formulário personalizado.

### Solicitar token de comerciante do Apple Pay

Se você configurou sua integração para [aceitar pagamentos com o Apple Pay](https://docs.stripe.com/payments/accept-a-payment.md?payment-ui=elements&api-integration=checkout), recomendamos configurar a interface do Apple Pay para retornar um token do comerciante, a fim de habilitar transações iniciadas pelo comerciante (MIT). [Solicite o tipo de token do comerciante pertinente](https://docs.stripe.com/apple-pay/merchant-tokens.md?pay-element=web-pe) no Payment Element.

### Envie os pagamentos para Stripe (Client-side)

Use [stripe.confirmPayment](https://docs.stripe.com/js/payment_intents/confirm_payment) para concluir o pagamento utilizando os detalhes do Payment Element. Forneça um [return_url](https://docs.stripe.com/api/payment_intents/create.md#create_payment_intent-return_url) a essa função para indicar para onde a Stripe deve redirecionar o usuário após a conclusão do pagamento. Seu usuário pode ser redirecionado primeiro para um site intermediário, como uma página de autorização bancária, antes de ser redirecionado para o `return_url`. Os pagamentos com cartão são redirecionados imediatamente para o `return_url` quando um pagamento é finalizado.

Se não quiser redirecionar pagamentos com cartão após a conclusão do pagamento, defina [redirecionar](https://docs.stripe.com/js/payment_intents/confirm_payment#confirm_payment_intent-options-redirect) como `if_required`. Isso somente redireciona os clientes que fazem checkout com formas de pagamento baseadas em redirecionamento.

#### HTML + JS

```javascript
const form = document.getElementById('payment-form');

form.addEventListener('submit', async (event) => {
  event.preventDefault();
const {error} = await stripe.confirmPayment({
    //`Elements` instance that was used to create the Payment Element
    elements,
    confirmParams: {
      return_url: 'https://example.com/order/123/complete',
    },
  });

  if (error) {
    // This point will only be reached if there is an immediate error when
    // confirming the payment. Show error to your customer (for example, payment
    // details incomplete)
    const messageContainer = document.querySelector('#error-message');
    messageContainer.textContent = error.message;
  } else {
    // Your customer will be redirected to your `return_url`. For some payment
    // methods like iDEAL, your customer will be redirected to an intermediate
    // site first to authorize the payment, then redirected to the `return_url`.
  }
});
```

#### React

Para chamar [stripe.confirmPayment](https://docs.stripe.com/js/payment_intents/confirm_payment) do seu componente de formulário de pagamento, use os hooks [useStripe](https://docs.stripe.com/sdks/stripejs-react.md#usestripe-hook) e [useElements](https://docs.stripe.com/sdks/stripejs-react.md#useelements-hook).

Se preferir componentes de classe tradicionais em vez de hooks, use um [ElementsConsumer](https://docs.stripe.com/sdks/stripejs-react.md#elements-consumer).

```jsx
import React, {useState} from 'react';
import {useStripe, useElements, PaymentElement} from '@stripe/react-stripe-js';

const CheckoutForm = () => {
  const stripe = useStripe();
  const elements = useElements();

  const [errorMessage, setErrorMessage] = useState(null);

  const handleSubmit = async (event) => {
    // We don't want to let default form submission happen here,
    // which would refresh the page.
    event.preventDefault();

    if (!stripe || !elements) {
      // Stripe.js hasn't yet loaded.
      // Make sure to disable form submission until Stripe.js has loaded.
      return;
    }
const {error} = await stripe.confirmPayment({
      //`Elements` instance that was used to create the Payment Element
      elements,
      confirmParams: {
        return_url: 'https://example.com/order/123/complete',
      },
    });


    if (error) {
      // This point will only be reached if there is an immediate error when
      // confirming the payment. Show error to your customer (for example, payment
      // details incomplete)
      setErrorMessage(error.message);
    } else {
      // Your customer will be redirected to your `return_url`. For some payment
      // methods like iDEAL, your customer will be redirected to an intermediate
      // site first to authorize the payment, then redirected to the `return_url`.
    }
  };

  return (
    <form onSubmit={handleSubmit}>
      <PaymentElement />
      <button disabled={!stripe}>Submit</button>
      {/* Show error message to your customers */}
      {errorMessage && <div>{errorMessage}</div>}
    </form>
  );
};

export default CheckoutForm;
```

Verifique se o `return_url` corresponde a uma página no seu site que fornece o status do pagamento. Quando a Stripe redireciona o cliente para o `return_url`, nós fornecemos os seguintes parâmetros de consulta de URL:

| Parâmetro                      | Descrição                                                                                                                                    |
| ------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------- |
| `payment_intent`               | O identificador único do `PaymentIntent`.                                                                                                    |
| `payment_intent_client_secret` | O [segredo do cliente](https://docs.stripe.com/api/payment_intents/object.md#payment_intent_object-client_secret) do objeto `PaymentIntent`. |

> Se você tiver ferramentas que rastreiam a sessão do cliente no navegador, pode ser necessário adicionar o domínio `stripe.com` à lista de exclusão de referenciadores. Os redirecionamentos fazem com que algumas ferramentas criem novas sessões, o que impede que você rastreie a sessão completa.

Use um dos parâmetros de consulta para recuperar o PaymentIntent. Inspecione o [status do PaymentIntent](https://docs.stripe.com/payments/paymentintents/lifecycle.md) para decidir o que mostrar aos clientes. Você também pode anexar seus próprios parâmetros de consulta ao fornecer o `return_url`, que persiste durante o processo de redirecionamento.

#### HTML + JS

```javascript

// Initialize Stripe.js using your publishable key
const stripe = Stripe('<<YOUR_PUBLISHABLE_KEY>>');

// Retrieve the "payment_intent_client_secret" query parameter appended to
// your return_url by Stripe.js
const clientSecret = new URLSearchParams(window.location.search).get(
  'payment_intent_client_secret'
);

// Retrieve the PaymentIntent
stripe.retrievePaymentIntent(clientSecret).then(({paymentIntent}) => {
  const message = document.querySelector('#message')

  // Inspect the PaymentIntent `status` to indicate the status of the payment
  // to your customer.
  //
  // Some payment methods will [immediately succeed or fail][0] upon
  // confirmation, while others will first enter a `processing` state.
  //
  // [0]: https://stripe.com/docs/payments/payment-methods#payment-notification
  switch (paymentIntent.status) {
    case 'succeeded':
      message.innerText = 'Success! Payment received.';
      break;

    case 'processing':
      message.innerText = "Payment processing. We'll update you when payment is received.";
      break;

    case 'requires_payment_method':
      message.innerText = 'Payment failed. Please try another payment method.';
      // Redirect your user back to your payment page to attempt collecting
      // payment again
      break;

    default:
      message.innerText = 'Something went wrong.';
      break;
  }
});
```

#### React

```jsx
import React, {useState, useEffect} from 'react';
import {useStripe} from '@stripe/react-stripe-js';

const PaymentStatus = () => {
  const stripe = useStripe();
  const [message, setMessage] = useState(null);

  useEffect(() => {
    if (!stripe) {
      return;
    }

    // Retrieve the "payment_intent_client_secret" query parameter appended to
    // your return_url by Stripe.js
    const clientSecret = new URLSearchParams(window.location.search).get(
      'payment_intent_client_secret'
    );

    // Retrieve the PaymentIntent
    stripe
      .retrievePaymentIntent(clientSecret)
      .then(({paymentIntent}) => {
        // Inspect the PaymentIntent `status` to indicate the status of the payment
        // to your customer.
        //
        // Some payment methods will [immediately succeed or fail][0] upon
        // confirmation, while others will first enter a `processing` state.
        //
        // [0]: https://stripe.com/docs/payments/payment-methods#payment-notification
        switch (paymentIntent.status) {
          case 'succeeded':
            setMessage('Success! Payment received.');
            break;

          case 'processing':
            setMessage("Payment processing. We'll update you when payment is received.");
            break;

          case 'requires_payment_method':
            // Redirect your user back to your payment page to attempt collecting
            // payment again
            setMessage('Payment failed. Please try another payment method.');
            break;

          default:
            setMessage('Something went wrong.');
            break;
        }
      });
  }, [stripe]);


  return message;
};

export default PaymentStatus;
```

### Gerencie eventos pós-pagamento (Server-side)

Stripe envia um evento [payment_intent.succeeded](https://docs.stripe.com/api/events/types.md#event_types-payment_intent.succeeded) quando o pagamento é concluído. Use a [ferramenta Dashboard webhook](https://dashboard.stripe.com/webhooks) ou siga o [guia de webhooks](https://docs.stripe.com/webhooks/quickstart.md) 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](https://stripe.com/payments/payment-methods-guide) 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:

| Evento                                                                                                                          | Descrição                                                                                                                                                                                                                                                                     | Ação                                                                                                                                                                                            |
| ------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [payment_intent.succeeded](https://docs.stripe.com/api/events/types.md?lang=php#event_types-payment_intent.succeeded)           | Enviado quando um cliente conclui um pagamento com êxito.                                                                                                                                                                                                                     | Envie ao cliente uma confirmação de pedido e *processe* (Fulfillment is the process of providing the goods or services purchased by a customer, typically after payment is collected) o pedido. |
| [payment_intent.processing](https://docs.stripe.com/api/events/types.md?lang=php#event_types-payment_intent.processing)         | Enviado quando um cliente inicia um pagamento, mas o pagamento ainda precisa ser concluído. Esse evento costuma ser enviado quando um cliente inicia um débito bancário. Ele é seguido por um evento `payment_intent.succeeded` ou `payment_intent.payment_failed` no futuro. | Envie ao cliente uma confirmação do pedido que indica que o pagamento está pendente. Para produtos digitais, pode ser necessário executar o pedido antes de aguardar a conclusão do pagamento.  |
| [payment_intent.payment_failed](https://docs.stripe.com/api/events/types.md?lang=php#event_types-payment_intent.payment_failed) | Enviado quando um cliente tenta fazer um pagamento, mas o pagamento falha.                                                                                                                                                                                                    | Se um pagamento passa de `processing` para `payment_failed`, ofereça ao cliente outra tentativa para pagar.                                                                                     |

## Testes

Teste seu fluxo de criação de conta [criando contas](https://docs.stripe.com/connect/testing.md#creating-accounts) e [usando OAuth](https://docs.stripe.com/connect/testing.md#using-oauth).

#### Cartões

| Número do cartão    | Cenário                                                                                                                                                                                                                                                                                             | Como testar                                                                                                                 |
| ------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------- |
| 4242424242424242    | O pagamento com cartão é bem-sucedido e não precisa de autenticação.                                                                                                                                                                                                                                | Preencha o formulário do cartão de crédito usando o número do cartão de crédito com qualquer validade, CVC e código postal. |
| 4000002500003155    | O pagamento com cartão precisa de *autenticação* (Strong Customer Authentication (SCA) is a regulatory requirement in effect as of September 14, 2019, that impacts many European online payments. It requires customers to use two-factor authentication like 3D Secure to verify their purchase). | Preencha o formulário do cartão de crédito usando o número do cartão de crédito com qualquer validade, CVC e código postal. |
| 4000000000009995    | O cartão é recusado com um código de recusa como `insufficient_funds`.                                                                                                                                                                                                                              | Preencha o formulário do cartão de crédito usando o número do cartão de crédito com qualquer validade, CVC e código postal. |
| 6205500000000000004 | O cartão UnionPay tem um comprimento variável de 13 a 19 dígitos.                                                                                                                                                                                                                                   | Preencha o formulário do cartão de crédito usando o número do cartão de crédito com qualquer validade, CVC e código postal. |

#### Carteiras

| Forma de pagamento | Cenário                                                                                                                                                                   | Como testar                                                                                                                                                                                                    |
| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Alipay             | O cliente paga com uma forma de pagamento baseada em redirecionamento e [notificação imediata](https://docs.stripe.com/payments/payment-methods.md#payment-notification). | Escolha qualquer forma de pagamento baseada em redirecionamento, preencha os dados obrigatórios e confirme o pagamento. Em seguida, clique em **Concluir o pagamento de teste** na página de redirecionamento. |

#### Débito bancário autenticado

| Forma de pagamento                   | Cenário                                                                                                                                                                                                | Como testar                                                                                                                                                                                                |
| ------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Débito automático BECS               | O cliente paga com débito automático BECS.                                                                                                                                                             | Preencha o formulário usando o número de conta `900123456` e BSB `000000`. Inicialmente, o status do PaymentIntent muda para `processing` e, 3 minutos depois, para `succeeded`.                           |
| Débito automático BECS               | O pagamento do cliente falha com um código de erro `account_closed`.                                                                                                                                   | Preencha o formulário usando o número da conta `111111113` e BSB `000000`.                                                                                                                                 |
| Bancontact, EPS, iDEAL, e Przelewy24 | Seu cliente não faz a autenticação na página de redirecionamento de uma forma de pagamento baseada em redirecionamento e notificação imediata.                                                         | Escolha qualquer forma de pagamento baseada em redirecionamento, preencha os dados obrigatórios e confirme o pagamento. Em seguida, clique em **Falhar pagamento de teste** na página de redirecionamento. |
| Pay by Bank                          | O cliente paga com uma forma de pagamento baseada em redirecionamento e [notificação posterior](https://docs.stripe.com/payments/payment-methods.md#payment-notification).                             | Escolha a forma de pagamento, preencha os dados obrigatórios e confirme o pagamento. Em seguida, clique em **Concluir o pagamento de teste** na página de redirecionamento.                                |
| Pay by Bank                          | Seu cliente não faz a autenticação na página de redirecionamento de uma forma de pagamento baseada em redirecionamento e notificação posterior.                                                        | Escolha a forma de pagamento, preencha os dados obrigatórios e confirme o pagamento. Em seguida, clique em **Falhar o pagamento de teste** na página de redirecionamento.                                  |
| BLIK                                 | Os pagamentos BLIK falham de várias formas: falhas imediatas (por exemplo, o código está vencido ou inválido), erros atrasados (o banco recusa) ou limites de tempo (o cliente não respondeu a tempo). | Use padrões de e-mail para [simular as diferentes falhas.](https://docs.stripe.com/payments/blik/accept-a-payment.md#simulate-failures)                                                                    |

#### Débitos bancários

| Forma de pagamento     | Cenário                                                                                           | Como testar                                                                                                                                                                     |
| ---------------------- | ------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Débito automático SEPA | O cliente paga com débito automático SEPA.                                                        | Preencha o formulário usando o número de conta `AT321904300235473204`. Inicialmente, o status do PaymentIntent muda para processando e, três minutos depois, para bem-sucedido. |
| Débito automático SEPA | O status da intenção de pagamento do cliente muda de `processing` para `requires_payment_method`. | Preencha o formulário usando o número de conta `AT861904300235473202`.                                                                                                          |

#### Boletos

| Forma de pagamento | Cenário                                          | Como testar                                                                                    |
| ------------------ | ------------------------------------------------ | ---------------------------------------------------------------------------------------------- |
| Boleto, OXXO       | Seu cliente paga com um boleto ou uma guia OXXO. | Selecione boleto ou OXXO como forma de pagamento e envie o pagamento. Feche o diálogo exibido. |

Consulte [Testes](https://docs.stripe.com/testing.md) para obter mais informações sobre como testar sua integração.


# Descrição da compra

> This is a Descrição da compra for when platform is ios and mobile-ui is payment-sheet. View the full page at https://docs.stripe.com/connect/end-to-end-marketplace?platform=ios&mobile-ui=payment-sheet.
![](https://b.stripecdn.com/docs-statics-srv/assets/ios-overview.9e0d68d009dc005f73a6f5df69e00458.png)

Integre a IU de pagamento pré-criada da Stripe no checkout do seu aplicativo iOS com a classe [PaymentSheet](https://stripe.dev/stripe-ios/stripe-paymentsheet/Classes/PaymentSheet.html). Veja nosso exemplo de integração [no GitHub](https://github.com/stripe/stripe-ios/tree/master/Example/PaymentSheet%20Example).

> #### Accounts v2 API support
> 
> The Payment Sheet doesn’t support *customer-configured Accounts* (Account configurations represent role-based functionality that you can enable for accounts, such as merchant, customer, or recipient). It only supports `Customer` objects.

Este guia mostra como aceitar pagamentos e movimentar fundos para as contas bancárias dos seus vendedores ou prestadores de serviços. Para fins de demonstração, criaremos um marketplace de locações residenciais que conecta proprietários a pessoas que querem alugar um imóvel. Você pode usar os conceitos deste guia para outras situações.

## Pré-requisitos

1. [Cadastre sua plataforma](https://dashboard.stripe.com/connect).
1. [Verifique e adicione os dados da empresa no Dashboard](https://dashboard.stripe.com/account/onboarding).
1. [Conclua seu perfil da plataforma](https://dashboard.stripe.com/connect/settings/profile).
1. [Personalize as configurações da sua marca](https://dashboard.stripe.com/settings/connect/stripe-dashboard/branding). Adicione um nome de empresa, ícone e cor da marca.

## Configurar a Stripe [Lado do servidor] [Lado do cliente]

Primeiro, você precisa de uma conta Stripe. [Inscreva-se aqui](https://dashboard.stripe.com/register).

### Lado do servidor

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

#### Ruby

```bash
# Available as a gem
sudo gem install stripe
```

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

### Lado do cliente

O [SDK da Stripe para iOS](https://github.com/stripe/stripe-ios) é de código aberto, [totalmente documentado](https://stripe.dev/stripe-ios/index.html) e compatível com aplicativos que aceitam iOS 13 ou versões mais recentes.

#### Gerenciador de pacotes Swift

Para instalar o SDK, siga estas etapas:

1. No Xcode, selecione **Arquivo** > **Adicionar dependências de pacote…** e insira `https://github.com/stripe/stripe-ios-spm` como URL do repositório.
1. Selecione o número da última versão da nossa [página de lançamentos](https://github.com/stripe/stripe-ios/releases).
1. Adicione o produto **StripePaymentsUI** ao [alvo do seu aplicativo](https://developer.apple.com/documentation/swift_packages/adding_package_dependencies_to_your_app).

#### CocoaPods

1. Se ainda não o fez, instale a versão mais recente do [CocoaPods](https://guides.cocoapods.org/using/getting-started.html).
1. Se não tiver um [Podfile](https://guides.cocoapods.org/syntax/podfile.html), execute o seguinte comando para criar um:
   ```bash
   pod init
   ```
1. Adicione esta linha ao seu `Podfile`:
   ```podfile
   pod 'StripePaymentsUI'
   ```
1. Execute o seguinte comando:
   ```bash
   pod install
   ```
1. Não se esqueça de usar o arquivo `.xcworkspace` para abrir seu projeto em Xcode, em vez do arquivo `.xcodeproj`, daqui em diante.
1. No futuro, para atualizar para a versão mais recente do SDK, execute:
   ```bash
   pod update StripePaymentsUI
   ```

#### Carthage

1. Se ainda não o fez, instale a versão mais recente do [Carthage](https://github.com/Carthage/Carthage#installing-carthage).
1. Adicione esta linha ao seu `Cartfile`:
   ```cartfile
   github "stripe/stripe-ios"
   ```
1. Siga as [instruções de instalação do Carthage](https://github.com/Carthage/Carthage#if-youre-building-for-ios-tvos-or-watchos). Certifique-se de integrar todas as estruturas necessárias listadas [here](https://github.com/stripe/stripe-ios/tree/master/StripePaymentsUI/README.md#manual-linking).
1. No futuro, para atualizar para a versão mais recente do SDK, execute o seguinte comando:
   ```bash
   carthage update stripe-ios --platform ios
   ```

#### Estrutura manual

1. Vá até a nossa [página de lançamentos do GitHub](https://github.com/stripe/stripe-ios/releases/latest) e baixe e descompacte o **Stripe.xcframework.zip**.
1. Arraste **StripePaymentsUI.xcframework** até a seção **Embedded Binaries** das configurações **General** no seu projeto Xcode. Certifique-se de selecionar **Copy items if needed**.
1. Repita a etapa 2 para todas as estruturas necessárias listadas [here](https://github.com/stripe/stripe-ios/tree/master/StripePaymentsUI/README.md#manual-linking).
1. No futuro, para atualizar para a versão mais recente do nosso SDK, repita as etapas 1 a 3.

> Para obter mais informações sobre a versão mais recente e as versões anteriores do SDK, consulte a página [Lançamentos](https://github.com/stripe/stripe-ios/releases) no GitHub. Para receber notificações quando um novo lançamento for publicado, [assista aos lançamentos](https://help.github.com/en/articles/watching-and-unwatching-releases-for-a-repository#watching-releases-for-a-repository) do repositório.

Configure o SDK com sua [chave publicável da Stripe](https://dashboard.stripe.com/test/apikeys) na inicialização do aplicativo. Isso permite que seu aplicativo faça solicitações à API da Stripe .

#### Swift

```swift
import UIKitimportStripePaymentsUI

@main
class AppDelegate: UIResponder, UIApplicationDelegate {

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

> Use suas [chaves de teste](https://docs.stripe.com/keys.md#obtain-api-keys) enquanto testa e desenvolve, e suas chaves de [modo de produção](https://docs.stripe.com/keys.md#test-live-modes) quando publicar seu aplicativo.

## Criar uma conta conectada

#### Accounts v2

Quando um vendedor ou provedor de serviços se cadastra na sua plataforma, crie uma [conta conectada](https://docs.stripe.com/api/v2/core/accounts.md) que o represente. A conta conectada permite que você recolha suas informações de identificação, aceite pagamentos para eles e transfira fundos para a conta bancária deles. Em nosso exemplo de aluguel de casas, a conta conectada representa o proprietário da casa.

#### Accounts v1

Quando um vendedor ou provedor de serviços se cadastra na sua plataforma, crie uma [conta conectada](https://docs.stripe.com/api/accounts.md) que o represente. A conta conectada permite que você recolha suas informações de identificação, aceite pagamentos para eles e transfira fundos para a conta bancária deles. Em nosso exemplo de aluguel de casas, a conta conectada representa o proprietário da casa.
![](https://b.stripecdn.com/docs-statics-srv/assets/express-ios.6789c3d9f8e327847abb218d75a29eec.png)

> Este guia usa contas Express com determinadas [restrições](https://docs.stripe.com/connect/express-accounts.md#prerequisites-for-using-express). Você também tem a opção de avaliar [contas Custom](https://docs.stripe.com/connect/custom-accounts.md).

### Crie uma conta conectada com informações pré-preenchidas

#### Accounts v2

Use a API `/v2/core/accounts` para [criar](https://docs.stripe.com/api/v2/core/accounts/create.md) uma conta conectada, especificando o [dashboard da conta conectada e as responsabilidades](https://docs.stripe.com/connect/accounts-v2/connected-account-configuration.md).

```curl
curl -X POST https://api.stripe.com/v2/core/accounts \
  -H "Authorization: Bearer <<YOUR_SECRET_KEY>>" \
  -H "Stripe-Version: 2026-01-28.clover" \
  --json '{
    "contact_email": "furever_contact@example.com",
    "display_name": "Furever",
    "defaults": {
        "responsibilities": {
            "fees_collector": "application",
            "losses_collector": "application"
        }
    },
    "dashboard": "express",
    "identity": {
        "business_details": {
            "registered_name": "Furever"
        },
        "country": "us",
        "entity_type": "company"
    },
    "configuration": {
        "merchant": {
            "capabilities": {
                "card_payments": {
                    "requested": true
                }
            }
        },
        "recipient": {
            "capabilities": {
                "stripe_balance": {
                    "stripe_transfers": {
                        "requested": true
                    }
                }
            }
        }
    },
    "include": [
        "configuration.merchant",
        "configuration.recipient",
        "identity",
        "requirements"
    ]
  }'
```

Se você já coletou dados de suas contas conectadas, pode usá-los para preencher o objeto `Account`. Você pode preencher quaisquer dados de conta, inclusive dados pessoais e comerciais, dados de contas externas e muito mais.

Após criar uma `Conta`, crie uma [Pessoa](https://docs.stripe.com/api/v2/core/persons/create.md) para representar a pessoa responsável por abrir a conta, definindo como verdadeiro `relationship.representative` e todas as informações da conta que você queira preencher previamente (por exemplo, o nome e sobrenome).

```curl
curl -X POST https://api.stripe.com/v2/core/accounts/{{ACCOUNT_ID}}/persons \
  -H "Authorization: Bearer <<YOUR_SECRET_KEY>>" \
  -H "Stripe-Version: 2026-04-22.preview" \
  --json '{
    "given_name": "Jenny",
    "surname": "Rosen",
    "email": "jenny.rosen@example.com",
    "relationship": {
        "representative": true
    }
  }'
```

O Connect Onboarding não solicita as informações pré-preenchidas. No entanto, ele solicita que o titular da conta confirme as informações pré-preenchidas antes de aceitar o [contrato de serviços do Connect](https://docs.stripe.com/connect/service-agreement-types.md).

Ao testar sua integração, preencha antecipadamente os dados da conta usando [dados de teste](https://docs.stripe.com/connect/testing.md).

### Criar um link da conta

Você pode criar um link de conta chamando a API [Account Links v2](https://docs.stripe.com/api/v2/core/account-links.md) com os seguintes parâmetros:

- `account`
- `refresh_url`
- `return_url`
- `type` = `account_onboarding`
- `configurations` = `recipient` e `merchant`

```curl
curl -X POST https://api.stripe.com/v2/core/account_links \
  -H "Authorization: Bearer <<YOUR_SECRET_KEY>>" \
  -H "Stripe-Version: 2025-08-27.preview" \
  --json '{
    "account": "{{CONNECTEDACCOUNT_ID}}",
    "use_case": {
        "type": "account_onboarding",
        "account_onboarding": {
            "configurations": [
                "recipient",
                "merchant"
            ],
            "refresh_url": "https://example.com/reauth",
            "return_url": "https://example.com/return"
        }
    }
  }'
```

### Redirecionar o usuário ao URL do link da conta

A resposta de criação do link da conta inclui um valor de `url`. Após autenticar o usuário no seu aplicativo, redirecione-o para essa URL para inseri-lo no fluxo. As URLs de link da conta são temporárias e de uso único, pois concedem acesso às informações pessoais do usuário da conta conectada. Se desejar preencher previamente as informações, deverá preencher antes de gerar o link da conta. Depois de criar o link da conta, não será possível ler nem gravar informações na conta conectada.

> Não envie URLs de links de conta por e-mail, SMS ou outra maneira para fora do aplicativo da sua plataforma. Em vez disso, forneça-os ao titular da conta autenticado dentro do seu aplicativo.

#### Item 1

#### Swift

```swift
import UIKit
import SafariServices

let BackendAPIBaseURL: String = "" // Set to the URL of your backend server

class ConnectOnboardViewController: UIViewController {

    // ...

    override func viewDidLoad() {
        super.viewDidLoad()

        let connectWithStripeButton = UIButton(type: .system)
        connectWithStripeButton.setTitle("Connect with Stripe", for: .normal)
        connectWithStripeButton.addTarget(self, action: #selector(didSelectConnectWithStripe), for: .touchUpInside)
        view.addSubview(connectWithStripeButton)

        // ...
    }

    @objc
    func didSelectConnectWithStripe() {
        if let url = URL(string: BackendAPIBaseURL)?.appendingPathComponent("onboard-user") {
          var request = URLRequest(url: url)
          request.httpMethod = "POST"
          let task = URLSession.shared.dataTask(with: request) { (data, response, error) in
              guard let data = data,
                  let json = try? JSONSerialization.jsonObject(with: data, options: []) as? [String : Any],
                  let accountURLString = json["url"] as? String,
                  let accountURL = URL(string: accountURLString) else {
                      // handle error
              }

              let safariViewController = SFSafariViewController(url: accountURL)
              safariViewController.delegate = self

              DispatchQueue.main.async {
                  self.present(safariViewController, animated: true, completion: nil)
              }
          }
        }
    }

    // ...
}

extension ConnectOnboardViewController: SFSafariViewControllerDelegate {
    func safariViewControllerDidFinish(_ controller: SFSafariViewController) {
        // the user may have closed the SFSafariViewController instance before a redirect
        // occurred. Sync with your backend to confirm the correct state
    }
}

```

#### Item 2

```xml
<?xml version="1.0" encoding="utf-8"?>
<androidx.constraintlayout.widget.ConstraintLayout
    xmlns:android="http://schemas.android.com/apk/res/android"
    xmlns:app="http://schemas.android.com/apk/res-auto"
    xmlns:tools="http://schemas.android.com/tools"
    android:layout_width="match_parent"
    android:layout_height="match_parent"
    tools:context=".activity.ConnectWithStripeActivity">

    <Button
        android:id="@+id/connect_with_stripe"
        android:text="Connect with Stripe"
        android:layout_height="wrap_content"
        android:layout_width="wrap_content"
        app:layout_constraintBottom_toBottomOf="parent"
        app:layout_constraintEnd_toEndOf="parent"
        app:layout_constraintStart_toStartOf="parent"
        app:layout_constraintTop_toTopOf="parent"
        style="?attr/materialButtonOutlinedStyle"
        />

</androidx.constraintlayout.widget.ConstraintLayout>
```

#### Kotlin

```kotlin
class ConnectWithStripeActivity : AppCompatActivity() {

    private val viewBinding: ActivityConnectWithStripeViewBinding by lazy {
        ActivityConnectWithStripeViewBinding.inflate(layoutInflater)
    }
    private val httpClient = OkHttpClient()

    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        setContentView(viewBinding.root)

        viewBinding.connectWithStripe.setOnClickListener {
            val weakActivity = WeakReference<Activity>(this)
            val request = Request.Builder()
                .url(BACKEND_URL + "onboard-user")
                .post("".toRequestBody())
                .build()
            httpClient.newCall(request)
                .enqueue(object: Callback {
                    override fun onFailure(call: Call, e: IOException) {
                        // Request failed
                    }
                    override fun onResponse(call: Call, response: Response) {
                        if (!response.isSuccessful) {
                            // Request failed
                        } else {
                            val responseData = response.body?.string()
                            val responseJson =
                                responseData?.let { JSONObject(it) } ?: JSONObject()
                            val url = responseJson.getString("url")

                            weakActivity.get()?.let {
                                val builder: CustomTabsIntent.Builder = CustomTabsIntent.Builder()
                                val customTabsIntent = builder.build()
                                customTabsIntent.launchUrl(it, Uri.parse(url))
                            }
                        }
                    }
                })
        }
    }

    internal companion object {
        internal const val BACKEND_URL = "https://example-backend-url.com/"
    }
}
```

#### Item 3

### Gerenciar o usuário que volta à plataforma

O Connect Onboarding exige que você passe tanto um `return_url` quanto um `refresh_url` para lidar com todos os casos em que o usuário da conta é redirecionado para a sua plataforma.

> Você pode usar HTTP para seu `return_url` e para o `refresh_url` enquanto estiver em um ambiente de teste (por exemplo, para testar com o localhost), mas modo de produção aceita apenas HTTPS. Você deve atualizar URLs de teste para URLs HTTPS antes do lançamento.

#### return_url

A Stripe emite um redirecionamento para essa URL quando o usuário da conta conectada conclui o fluxo de onboarding. Isso não significa que todas as informações tenham sido recolhidas ou que não haja requisitos pendentes na conta. Significa apenas que o fluxo foi inserido e encerrado corretamente.

Nenhum estado é transmitido por essa URL. Depois que um usuário for redirecionado para o seu `return_url`, verifique o estado dos requisitos na conta dele fazendo o seguinte:

- Ouça os Webhooks `v2.core.account[requirements].updated`.
- Chame a API [Accounts v2](https://docs.stripe.com/api/v2/core/accounts/retrieve.md) e inspecione o objeto retornado.

#### refresh_url

A Stripe redireciona seu usuário para o `refresh_url` nestes casos:

- O link expirou (alguns minutos se passaram desde a criação do link).
- O usuário já acessou o URL (atualizou a página ou clicou em Voltar ou Avançar no navegador).
- Sua plataforma não consegue mais acessar a conta.
- A conta foi recusada.

Configure sua página `refresh_url` para acionar um método em seu servidor para chamar [Account Links v2](https://docs.stripe.com/api/v2/core/account-links.md) novamente com os mesmos parâmetros e redirecionar o usuário para o novo link.

### Gerenciar usuários que não concluíram o onboarding

Um usuário redirecionado para o seu `return_url` pode não ter concluído o processo de onboarding. Use o endpoint `/v2/core/accounts` para recuperar a conta do usuário e verificar se [configuration.recipient.capabilities.stripe_balance.stripe_transfers.status](https://docs.stripe.com/api/v2/core/accounts/object.md#v2_account_object-configuration-recipient-capabilities-stripe_balance-stripe_transfers-status) está coo `active`. Se o status não estiver `active` e [configuration.destinatário.capabilities.stripe_balance.stripe_transfers.status_details.code](https://docs.stripe.com/api/v2/core/accounts/object.md#v2_account_object-configuration-recipient-capabilities-stripe_balance-stripe_transfers-status_details-code) for `requirements_past_due`, forneça prompts na IU para permitir que o usuário continue o onboarding por meio de um novo link de conta. Para outros códigos, trate-os conforme necessário.

#### Accounts v1

Use a API `/v1/accounts` para [criar](https://docs.stripe.com/api/accounts/create.md) uma conta conectada especificando as [propriedades da conta conectada](https://docs.stripe.com/connect/migrate-to-controller-properties.md) ou o tipo de conta.

```curl
curl https://api.stripe.com/v1/accounts \
  -u "<<YOUR_SECRET_KEY>>:" \
  -d "controller[losses][payments]=application" \
  -d "controller[fees][payer]=application" \
  -d "controller[stripe_dashboard][type]=express"
```

Se você já coletou dados de suas contas conectadas, pode usá-los para preencher o objeto `Account`. Você pode preencher quaisquer dados de conta, inclusive dados pessoais e comerciais, dados de contas externas e muito mais.

Depois de criar uma `Account`, crie uma [Pessoa](https://docs.stripe.com/api/persons/create.md) para representar a pessoa responsável por abrir a conta, com `relationship.representative` definido como verdadeiro e informações da conta que você queira preencher previamente (por exemplo, o nome e sobrenome).

```curl
curl https://api.stripe.com/v1/accounts/{{ACCOUNT_ID}}/persons \
  -u "<<YOUR_SECRET_KEY>>:" \
  -d first_name=Jenny \
  -d last_name=Rosen \
  -d "relationship[representative]=true"
```

O Connect Onboarding não solicita as informações pré-preenchidas. No entanto, ele solicita que o titular da conta confirme as informações pré-preenchidas antes de aceitar o [contrato de serviços do Connect](https://docs.stripe.com/connect/service-agreement-types.md).

Ao testar sua integração, preencha antecipadamente os dados da conta usando [dados de teste](https://docs.stripe.com/connect/testing.md).

### Criar um link da conta

Você pode criar um link de conta chamando a API [Account Links v1](https://docs.stripe.com/api/account_links.md) com os seguintes parâmetros:

- `account`
- `refresh_url`
- `return_url`
- `type` = `account_onboarding`

```curl
curl https://api.stripe.com/v1/account_links \
  -u "<<YOUR_SECRET_KEY>>:" \
  -d "account={{CONNECTEDACCOUNT_ID}}" \
  --data-urlencode "refresh_url=https://example.com/reauth" \
  --data-urlencode "return_url=https://example.com/return" \
  -d type=account_onboarding
```

### Redirecionar o usuário ao URL do link da conta

A resposta da criação do link da conta inclui um valor de `url`. Após autenticar o usuário no seu aplicativo, redirecione-o para esta URL para inseri-lo no fluxo. As URLs de links de conta da [API Account Links v1](https://docs.stripe.com/api/account_links.md) são temporárias e de uso único, pois concedem acesso às informações pessoais do usuário da conta conectada. Autentique o usuário no seu aplicativo antes de redirecioná-lo para esta URL. Se desejar preencher previamente as informações, deverá preencher antes de gerar o link da conta. Depois de criar o link da conta, não será possível ler nem gravar informações da conta conectada.

> Não envie URLs de links de conta por e-mail, SMS ou outra maneira para fora do aplicativo da sua plataforma. Em vez disso, forneça-os ao titular da conta autenticado dentro do seu aplicativo.

#### Item 1

#### Swift

```swift
import UIKit
import SafariServices

let BackendAPIBaseURL: String = "" // Set to the URL of your backend server

class ConnectOnboardViewController: UIViewController {

    // ...

    override func viewDidLoad() {
        super.viewDidLoad()

        let connectWithStripeButton = UIButton(type: .system)
        connectWithStripeButton.setTitle("Connect with Stripe", for: .normal)
        connectWithStripeButton.addTarget(self, action: #selector(didSelectConnectWithStripe), for: .touchUpInside)
        view.addSubview(connectWithStripeButton)

        // ...
    }

    @objc
    func didSelectConnectWithStripe() {
        if let url = URL(string: BackendAPIBaseURL)?.appendingPathComponent("onboard-user") {
          var request = URLRequest(url: url)
          request.httpMethod = "POST"
          let task = URLSession.shared.dataTask(with: request) { (data, response, error) in
              guard let data = data,
                  let json = try? JSONSerialization.jsonObject(with: data, options: []) as? [String : Any],
                  let accountURLString = json["url"] as? String,
                  let accountURL = URL(string: accountURLString) else {
                      // handle error
              }

              let safariViewController = SFSafariViewController(url: accountURL)
              safariViewController.delegate = self

              DispatchQueue.main.async {
                  self.present(safariViewController, animated: true, completion: nil)
              }
          }
        }
    }

    // ...
}

extension ConnectOnboardViewController: SFSafariViewControllerDelegate {
    func safariViewControllerDidFinish(_ controller: SFSafariViewController) {
        // the user may have closed the SFSafariViewController instance before a redirect
        // occurred. Sync with your backend to confirm the correct state
    }
}

```

#### Item 2

```xml
<?xml version="1.0" encoding="utf-8"?>
<androidx.constraintlayout.widget.ConstraintLayout
    xmlns:android="http://schemas.android.com/apk/res/android"
    xmlns:app="http://schemas.android.com/apk/res-auto"
    xmlns:tools="http://schemas.android.com/tools"
    android:layout_width="match_parent"
    android:layout_height="match_parent"
    tools:context=".activity.ConnectWithStripeActivity">

    <Button
        android:id="@+id/connect_with_stripe"
        android:text="Connect with Stripe"
        android:layout_height="wrap_content"
        android:layout_width="wrap_content"
        app:layout_constraintBottom_toBottomOf="parent"
        app:layout_constraintEnd_toEndOf="parent"
        app:layout_constraintStart_toStartOf="parent"
        app:layout_constraintTop_toTopOf="parent"
        style="?attr/materialButtonOutlinedStyle"
        />

</androidx.constraintlayout.widget.ConstraintLayout>
```

#### Kotlin

```kotlin
class ConnectWithStripeActivity : AppCompatActivity() {

    private val viewBinding: ActivityConnectWithStripeViewBinding by lazy {
        ActivityConnectWithStripeViewBinding.inflate(layoutInflater)
    }
    private val httpClient = OkHttpClient()

    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        setContentView(viewBinding.root)

        viewBinding.connectWithStripe.setOnClickListener {
            val weakActivity = WeakReference<Activity>(this)
            val request = Request.Builder()
                .url(BACKEND_URL + "onboard-user")
                .post("".toRequestBody())
                .build()
            httpClient.newCall(request)
                .enqueue(object: Callback {
                    override fun onFailure(call: Call, e: IOException) {
                        // Request failed
                    }
                    override fun onResponse(call: Call, response: Response) {
                        if (!response.isSuccessful) {
                            // Request failed
                        } else {
                            val responseData = response.body?.string()
                            val responseJson =
                                responseData?.let { JSONObject(it) } ?: JSONObject()
                            val url = responseJson.getString("url")

                            weakActivity.get()?.let {
                                val builder: CustomTabsIntent.Builder = CustomTabsIntent.Builder()
                                val customTabsIntent = builder.build()
                                customTabsIntent.launchUrl(it, Uri.parse(url))
                            }
                        }
                    }
                })
        }
    }

    internal companion object {
        internal const val BACKEND_URL = "https://example-backend-url.com/"
    }
}
```

### Gerenciar o usuário que volta à plataforma

O Connect Onboarding exige que você passe um `return_url` e `refresh_url` para gerenciar todos os casos em que o usuário é redirecionado à sua plataforma. É importante implementá-los corretamente para proporcionar a melhor experiência ao usuário.

> Você pode usar HTTP para seu `return_url` e para o `refresh_url` enquanto estiver em um ambiente de teste (por exemplo, para testar com o localhost), mas modo de produção aceita apenas HTTPS. Você deve atualizar URLs de teste para URLs HTTPS antes do lançamento.

#### return_url

A Stripe emite um redirecionamento para essa URL quando o usuário da conta conectada conclui o fluxo de onboarding. Isso não significa que todas as informações tenham sido recolhidas ou que não haja requisitos pendentes na conta. Significa apenas que o fluxo foi inserido e encerrado corretamente.

Nenhum estado é passado por este URL. Após o redirecionamento de um usuário para o `return_url` , verifique o estado do parâmetro `details_submitted` na conta dele realizando uma das seguintes ações:

- Ouça os Webhooks `account.updated`
- Chame a API [Accounts v1](https://docs.stripe.com/api/accounts.md) e inspecione o objeto retornado

#### refresh_url

A Stripe redireciona seu usuário para o `refresh_url` nestes casos:

- O link expirou (alguns minutos se passaram desde a criação do link).
- O usuário já acessou o URL (atualizou a página ou clicou em Voltar ou Avançar no navegador).
- Sua plataforma não consegue mais acessar a conta.
- A conta foi recusada.

Configure sua página `refresh_url` para acionar um método em seu servidor para chamar [Account Links v1](https://docs.stripe.com/api/account_links.md) novamente com os mesmos parâmetros e redirecionar o usuário para o novo link.

### Gerenciar usuários que não concluíram o onboarding

Um usuário que é redirecionado para seu `return_url` pode não ter concluído o processo de onboarding. Use o endpoint `/v1/accounts` para recuperar a conta do usuário e verificar se `charges_enabled`. Se a conta não estiver totalmente integrada, forneça prompts de IU para permitir que o usuário continue fazendo onboarding por meio de um novo link de conta. Você pode determinar se eles concluíram o onboarding verificando o estado do parâmetro `details_submitted` na conta deles.

## Habilitar formas de pagamento

Veja as [configurações de formas de pagamento](https://dashboard.stripe.com/settings/connect/payment_methods) e ative as que pretende aceitar. Pagamentos com cartão, Google Pay e Apple Pay são ativados por padrão, mas você pode ativar e desativar as formas de pagamento conforme a necessidade.

Antes da exibição das formas de pagamento, a Stripe avalia a moeda, as restrições e outros parâmetros dessas formas de pagamento para criar a lista das que são aceitas. Priorizamos as que aumentam a conversão e são mais relevantes para a moeda e a localização do cliente. As formas de pagamento de menor prioridade são ocultas em um menu de estouro.

## Adicionar um endpoint [Lado do servidor]

> #### Nota
> 
> Para exibir o PaymentSheet antes de criar um PaymentIntent, consulte [Colete os dados de pagamento antes de criar um Intent](https://docs.stripe.com/payments/accept-a-payment-deferred.md?type=payment).

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

1. [PaymentIntent](https://docs.stripe.com/api/payment_intents.md): 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.

1. (Opcional) Uma [conta configurada pelo cliente](https://docs.stripe.com/api/v2/core/accounts/object.md#v2_account_object-applied_configurations) ou um objeto [Cliente](https://docs.stripe.com/api/customers.md): para configurar uma forma de pagamento para pagamentos futuros, você deve associá-la a um cliente. Crie um objeto para representar seu cliente quando ele criar uma conta na sua empresa. Se o cliente fizer um pagamento como convidado, você poderá criar um objeto `Conta` ou `Cliente` antes do pagamento e associá-lo à sua própria representação interna da conta do cliente posteriormente.

1. (Opcional) [CustomerSession](https://docs.stripe.com/api/customer_sessions.md): os dados do objeto que representa seu cliente são confidenciais e não podem ser recuperados diretamente de um aplicativo. Uma `CustomerSession` concede ao SDK acesso temporário e restrito à `Conta` ou ao `Cliente` e oferece opções de configuração adicionais. Consulte a lista completa de [opções de configuração](https://docs.stripe.com/api/customer_sessions/create.md#create_customer_session-components).

> Se você nunca salvar cartões para os clientes e não permitir que clientes recorrentes reutilizem cartões salvos, poderá omitir os objetos `Conta` ou `Cliente` e o objeto `CustomerSession` da sua integração.

Por motivos de segurança, o aplicativo não pode criar esses objetos. Para isso, adicione um endpoint ao servidor para:

1. Recupera a `Conta` ou o `Cliente` ou cria um novo.
1. Cria uma [CustomerSession](https://docs.stripe.com/api/customer_sessions.md) para a `Conta` ou o `Cliente`.
1. Cria um `PaymentIntent` com o [valor](https://docs.stripe.com/api/payment_intents/create.md#create_payment_intent-amount), a [moeda](https://docs.stripe.com/api/payment_intents/create.md#create_payment_intent-currency), e a [customer_account](https://docs.stripe.com/api/payment_intents/create.md#create_payment_intent-customer_account) ou o [cliente](https://docs.stripe.com/api/payment_intents/create.md#create_payment_intent-customer).
1. Retorna o *segredo do cliente* (The client secret is a unique key returned from Stripe as part of a PaymentIntent. This key lets the client access important fields from the PaymentIntent (status, amount, currency) while hiding sensitive ones (metadata, customer)) do `PaymentIntent`, o `client_secret` da `CustomerSession`, o ID da `Conta` ou do `Cliente` e sua [chave de publicação](https://dashboard.stripe.com/apikeys) do seu 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.

#### Gerenciar formas de pagamento no Dashboard

Você pode gerenciar formas de pagamento no [Dashboard](https://dashboard.stripe.com/settings/payment_methods). A Stripe processa a devolução de formas de pagamento qualificadas com base em fatores como valor, moeda e fluxo de pagamento da transação. O PaymentIntent é criado usando as formas de pagamento configuradas no Dashboard. Se não quiser usar o Dashboard ou se quiser especificar formas de pagamento manualmente, você pode listá-las usando o atributo `payment_method_types`.

#### curl

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

# Create an CustomerSession for the Customer
curl https://api.stripe.com/v1/customer_sessions \
  -u <<YOUR_SECRET_KEY>>: \
  -X "POST" \
  -d "customer"="{{CUSTOMER_ID}}" \
  -d "components[mobile_payment_element][enabled]"=true \
  -d "components[mobile_payment_element][features][payment_method_save]"=enabled \
  -d "components[mobile_payment_element][features][payment_method_redisplay]"=enabled \
  -d "components[mobile_payment_element][features][payment_method_remove]"=enabled

# Create a PaymentIntent
curl https://api.stripe.com/v1/payment_intents \
  -u <<YOUR_SECRET_KEY>>: \
  -X "POST" \
  -d "customer"="{{CUSTOMER_ID}}" \
  -d "amount"=1099 \
  -d "currency"="eur" \

  -d "automatic_payment_methods[enabled]"=true \
  -d application_fee_amount="123" \
  -d "transfer_data[destination]"="{{CONNECTED_ACCOUNT_ID}}" \
```

#### Listar manualmente as formas de pagamento

#### curl

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

# Create an CustomerSession for the Customer
curl https://api.stripe.com/v1/customer_sessions \
  -u <<YOUR_SECRET_KEY>>: \
  -X "POST" \
  -d "customer"="{{CUSTOMER_ID}}" \
  -d "components[mobile_payment_element][enabled]"=true \
  -d "components[mobile_payment_element][features][payment_method_save]"=enabled \
  -d "components[mobile_payment_element][features][payment_method_redisplay]"=enabled \
  -d "components[mobile_payment_element][features][payment_method_remove]"=enabled

# Create a PaymentIntent
curl https://api.stripe.com/v1/payment_intents \
  -u <<YOUR_SECRET_KEY>>: \
  -X "POST" \
  -d "customer"="{{CUSTOMER_ID}}" \
  -d "amount"=1099 \
  -d "currency"="eur" \
  -d "payment_method_types[]"="bancontact" \
  -d "payment_method_types[]"="card" \
  -d "payment_method_types[]"="ideal" \
  -d "payment_method_types[]"="klarna" \
  -d "payment_method_types[]"="sepa_debit" \
  -d application_fee_amount="123" \
  -d "transfer_data[destination]"="{{CONNECTED_ACCOUNT_ID}}" \
```

> A forma de pagamento precisa aceitar a moeda passada no PaymentIntent. Além disso, sua empresa precisa estar estabelecida em um dos países aceitos pela forma de pagamento. Consulte a página [Opções de integração de formas de pagamento](https://docs.stripe.com/payments/payment-methods/integration-options.md) para obter mais detalhes sobre o que é aceito.

## Integrar a descrição da compra [Lado do cliente]

To display the mobile Payment Element on your checkout screen:

- Mostrar os produtos que o cliente está comprando e o valor total
- Usar o [Address Element](https://docs.stripe.com/elements/address-element.md?platform=ios) para coletar todos os dados de envio necessários do cliente
- Adicionar um botão de checkout para exibir a IU da Stripe

#### UIKit

#### Accounts v2

In your app’s checkout screen, fetch the PaymentIntent client secret, `CustomerSession` client secret, customer-configured `Account` ID, and publishable key from the endpoint you created in the previous step. Use `STPAPIClient.shared` to set your publishable key and initialize the [PaymentSheet](https://stripe.dev/stripe-ios/stripe-paymentsheet/Classes/PaymentSheet.html).

#### iOS (Swift)

```swift
import UIKit@_spi(CustomerSessionBetaAccess) import StripePaymentSheet

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

  override func viewDidLoad() {
    super.viewDidLoad()

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

    // MARK: Fetch the PaymentIntent client secret, CustomerSession client secret, customer-configured Account 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 customerAccountId = json["customerAccount"] as? String,
            let customerSessionClientSecret = json["customerSessionClientSecret"] 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.customerAccount = .init(id: customerAccountId, customerSessionClientSecret: customerSessionClientSecret)
      // 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()
  }

}
```

#### Customers v1

In your app’s checkout screen, fetch the PaymentIntent client secret, `CustomerSession` client secret, `Customer` ID, and publishable key from the endpoint you created in the previous step. Use `STPAPIClient.shared` to set your publishable key and initialize the [PaymentSheet](https://stripe.dev/stripe-ios/stripe-paymentsheet/Classes/PaymentSheet.html).

#### iOS (Swift)

```swift
import UIKit@_spi(CustomerSessionBetaAccess) 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, CustomerSession client 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 customerSessionClientSecret = json["customerSessionClientSecret"] 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, customerSessionClientSecret: customerSessionClientSecret)
      // 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()
  }

}
```

Quando o cliente toca no botão **Checkout**, invoque `present` para apresentar a PaymentSheet. Após o cliente concluir o pagamento, a descrição é descartada e o bloco de conclusão é invocado com [PaymentSheetResult](https://stripe.dev/stripe-ios/stripe-paymentsheet/Enums/PaymentSheetResult.html).

#### iOS (Swift)

```swift
@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)")
    }
  }
}
```

#### SwiftUI

#### Accounts v2

Crie um modelo `ObservableObject` para sua tela de checkout. Esse modelo publica uma [PaymentSheet](https://stripe.dev/stripe-ios/stripe-paymentsheet/Classes/PaymentSheet.html) e um [PaymentSheetResult](https://stripe.dev/stripe-ios/stripe-paymentsheet/Enums/PaymentSheetResult.html).

```swift
import StripePaymentSheet
import SwiftUI

class CheckoutViewModel: ObservableObject {
  let backendCheckoutUrl = URL(string: "Your back-end endpoint/payment-sheet")! // Your back-end endpoint
  @Published var paymentSheet: PaymentSheet?
  @Published var paymentResult: PaymentSheetResult?
}
```

Fetch the PaymentIntent client secret, `CustomerSession` client secret, customer-configured `Account` ID, and publishable key from the endpoint you created in the previous step. Use `STPAPIClient.shared` to set your publishable key and initialize the [PaymentSheet](https://stripe.dev/stripe-ios/stripe-paymentsheet/Classes/PaymentSheet.html).

```swift
@_spi(CustomerSessionBetaAccess) import StripePaymentSheet
import SwiftUI

class CheckoutViewModel: ObservableObject {
  let backendCheckoutUrl = URL(string: "Your back-end endpoint/payment-sheet")! // Your back-end endpoint
  @Published var paymentSheet: PaymentSheet?
  @Published var paymentResult: PaymentSheetResult?
func preparePaymentSheet() {
    // MARK: Fetch thePaymentIntent and customer information from the back end
    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 customerAccountId = json["customerAccount"] as? String,
            let customerSessionClientSecret = json["customerSessionClientSecret"] as? String,
            letpaymentIntentClientSecret = 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.customerAccount = .init(id: customerAccountId, customerSessionClientSecret: customerSessionClientSecret)
      // Set `allowsDelayedPaymentMethods` to true if your business handles
      // delayed notification payment methods like US bank accounts.
      configuration.allowsDelayedPaymentMethods = true

      DispatchQueue.main.async {
        self.paymentSheet = PaymentSheet(paymentIntentClientSecret:paymentIntentClientSecret, configuration: configuration)
      }
    })
    task.resume()
  }
}
struct CheckoutView: View {
  @ObservedObject var model = CheckoutViewModel()

  var body: some View {
    VStack {
      if model.paymentSheet != nil {
        Text("Ready to pay.")
      } else {
        Text("Loading…")
      }
    }.onAppear { model.preparePaymentSheet() }
  }
}
```

Adicione um [PaymentSheet.PaymentButton](https://stripe.dev/stripe-ios/stripe-paymentsheet/Classes/PaymentSheet/PaymentButton.html) à sua `View`. O comportamento é similar a um `Button` SwiftUI, que permite ser personalizado com a adição de uma `View`. Quando você clica no botão, o PaymentSheet é exibido. Depois que você conclui o pagamento, a Stripe descarta a PaymentSheet e chama o gerenciador `onCompletion` com um objeto [PaymentSheetResult](https://stripe.dev/stripe-ios/stripe-paymentsheet/Enums/PaymentSheetResult.html).

```swift
@_spi(CustomerSessionBetaAccess) import StripePaymentSheet
import SwiftUI

class CheckoutViewModel: ObservableObject {
  let backendCheckoutUrl = URL(string: "Your back-end endpoint/payment-sheet")! // Your back-end endpoint
  @Published var paymentSheet: PaymentSheet?
  @Published var paymentResult: PaymentSheetResult?

  func preparePaymentSheet() {
    // MARK: Fetch the PaymentIntent and customer information from the back end
    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 customerAccountId = json["customerAccount"] as? String,
            let customerSessionClientSecret = json["customerSessionClientSecret"] 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.customerAccount = .init(id: customerAccountId, customerSessionClientSecret: customerSessionClientSecret)
      // Set `allowsDelayedPaymentMethods` to true if your business can handle payment methods
      // that complete payment after a delay, like SEPA Debit and Sofort.
      configuration.allowsDelayedPaymentMethods = true

      DispatchQueue.main.async {
        self.paymentSheet = PaymentSheet(paymentIntentClientSecret: paymentIntentClientSecret, configuration: configuration)
      }
    })
    task.resume()
  }
func onPaymentCompletion(result: PaymentSheetResult) {
    self.paymentResult = result
  }
}

struct CheckoutView: View {
  @ObservedObject var model = CheckoutViewModel()

  var body: some View {
    VStack {if let paymentSheet = model.paymentSheet {
        PaymentSheet.PaymentButton(
          paymentSheet: paymentSheet,
          onCompletion: model.onPaymentCompletion
        ) {
          Text("Buy")
        }
      } else {
        Text("Loading…")
      }if let result = model.paymentResult {
        switch result {
        case .completed:
          Text("Payment complete")
        case .failed(let error):
          Text("Payment failed: \(error.localizedDescription)")
        case .canceled:
          Text("Payment canceled.")
        }
      }
    }.onAppear { model.preparePaymentSheet() }
  }
}
```

#### Customers v1

Crie um modelo `ObservableObject` para sua tela de checkout. Esse modelo publica uma [PaymentSheet](https://stripe.dev/stripe-ios/stripe-paymentsheet/Classes/PaymentSheet.html) e um [PaymentSheetResult](https://stripe.dev/stripe-ios/stripe-paymentsheet/Enums/PaymentSheetResult.html).

```swift
import StripePaymentSheet
import SwiftUI

class CheckoutViewModel: ObservableObject {
  let backendCheckoutUrl = URL(string: "Your back-end endpoint/payment-sheet")! // Your back-end endpoint
  @Published var paymentSheet: PaymentSheet?
  @Published var paymentResult: PaymentSheetResult?
}
```

Fetch the PaymentIntent client secret, CustomerSession client secret, `Customer` ID, and publishable key from the endpoint you created in the previous step. Use `STPAPIClient.shared` to set your publishable key and initialize the [PaymentSheet](https://stripe.dev/stripe-ios/stripe-paymentsheet/Classes/PaymentSheet.html).

```swift
@_spi(CustomerSessionBetaAccess) import StripePaymentSheet
import SwiftUI

class CheckoutViewModel: ObservableObject {
  let backendCheckoutUrl = URL(string: "Your back-end endpoint/payment-sheet")! // Your back-end endpoint
  @Published var paymentSheet: PaymentSheet?
  @Published var paymentResult: PaymentSheetResult?
func preparePaymentSheet() {
    // MARK: Fetch thePaymentIntent and Customer information from the back end
    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 customerSessionClientSecret = json["customerSessionClientSecret"] as? String,
            letpaymentIntentClientSecret = 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, customerSessionClientSecret: customerSessionClientSecret)
      // Set `allowsDelayedPaymentMethods` to true if your business handles
      // delayed notification payment methods like US bank accounts.
      configuration.allowsDelayedPaymentMethods = true

      DispatchQueue.main.async {
        self.paymentSheet = PaymentSheet(paymentIntentClientSecret:paymentIntentClientSecret, configuration: configuration)
      }
    })
    task.resume()
  }
}
struct CheckoutView: View {
  @ObservedObject var model = CheckoutViewModel()

  var body: some View {
    VStack {
      if model.paymentSheet != nil {
        Text("Ready to pay.")
      } else {
        Text("Loading…")
      }
    }.onAppear { model.preparePaymentSheet() }
  }
}
```

Adicione um [PaymentSheet.PaymentButton](https://stripe.dev/stripe-ios/stripe-paymentsheet/Classes/PaymentSheet/PaymentButton.html) à sua `View`. O comportamento é similar a um `Button` SwiftUI, que permite ser personalizado com a adição de uma `View`. Quando você clica no botão, o PaymentSheet é exibido. Depois que você conclui o pagamento, a Stripe descarta a PaymentSheet e chama o gerenciador `onCompletion` com um objeto [PaymentSheetResult](https://stripe.dev/stripe-ios/stripe-paymentsheet/Enums/PaymentSheetResult.html).

```swift
@_spi(CustomerSessionBetaAccess) import StripePaymentSheet
import SwiftUI

class CheckoutViewModel: ObservableObject {
  let backendCheckoutUrl = URL(string: "Your back-end endpoint/payment-sheet")! // Your back-end endpoint
  @Published var paymentSheet: PaymentSheet?
  @Published var paymentResult: PaymentSheetResult?

  func preparePaymentSheet() {
    // MARK: Fetch the PaymentIntent and Customer information from the back end
    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 customerSessionClientSecret = json["customerSessionClientSecret"] 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, customerSessionClientSecret: customerSessionClientSecret)
      // Set `allowsDelayedPaymentMethods` to true if your business can handle payment methods
      // that complete payment after a delay, like SEPA Debit and Sofort.
      configuration.allowsDelayedPaymentMethods = true

      DispatchQueue.main.async {
        self.paymentSheet = PaymentSheet(paymentIntentClientSecret: paymentIntentClientSecret, configuration: configuration)
      }
    })
    task.resume()
  }
func onPaymentCompletion(result: PaymentSheetResult) {
    self.paymentResult = result
  }
}

struct CheckoutView: View {
  @ObservedObject var model = CheckoutViewModel()

  var body: some View {
    VStack {if let paymentSheet = model.paymentSheet {
        PaymentSheet.PaymentButton(
          paymentSheet: paymentSheet,
          onCompletion: model.onPaymentCompletion
        ) {
          Text("Buy")
        }
      } else {
        Text("Loading…")
      }if let result = model.paymentResult {
        switch result {
        case .completed:
          Text("Payment complete")
        case .failed(let error):
          Text("Payment failed: \(error.localizedDescription)")
        case .canceled:
          Text("Payment canceled.")
        }
      }
    }.onAppear { model.preparePaymentSheet() }
  }
}
```

Se `PaymentSheetResult` for `.completed`, informe ao cliente, por exemplo, exibindo uma tela de confirmação do pedido.

Configurar `allowsDelayedPaymentMethods` como verdadeiro permite formas de pagamento de [notificação assíncrona](https://docs.stripe.com/payments/payment-methods.md#payment-notification) 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.

## Configurar um URL de retorno [Lado do cliente]

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](https://developer.apple.com/documentation/xcode/defining-a-custom-url-scheme-for-your-app) e configure seu aplicativo delegado para encaminhar o URL ao SDK. A Stripe não aceita [links universais](https://developer.apple.com/documentation/xcode/allowing-apps-and-websites-to-link-to-your-content).

#### SceneDelegate

#### Swift

```swift
// 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
    }
}

```

#### AppDelegate

#### Swift

```swift
// This method handles opening custom URL schemes (for example, "your-app://stripe-redirect")
func application(_ app: UIApplication, open url: URL, options: [UIApplication.OpenURLOptionsKey: Any] = [:]) -> Bool {
    let stripeHandled = StripeAPI.handleURLCallback(with: url)
    if (stripeHandled) {
        return true
    } else {
        // This was not a Stripe url – handle the URL normally as you would
    }
    return false
}
```

#### SwiftUI

#### Swift

```swift

@main
struct MyApp: App {
  var body: some Scene {
    WindowGroup {
      Text("Hello, world!").onOpenURL { incomingURL in
          let stripeHandled = StripeAPI.handleURLCallback(with: incomingURL)
          if (!stripeHandled) {
            // This was not a Stripe url – handle the URL normally as you would
          }
        }
    }
  }
}
```

## Gerenciar eventos pós-pagamento [Lado do servidor]

Stripe envia um evento [payment_intent.succeeded](https://docs.stripe.com/api/events/types.md#event_types-payment_intent.succeeded) quando o pagamento é concluído. Use a [ferramenta Dashboard webhook](https://dashboard.stripe.com/webhooks) ou siga o [guia de webhooks](https://docs.stripe.com/webhooks/quickstart.md) 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](https://stripe.com/payments/payment-methods-guide) 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:

| Evento                                                                                                                          | Descrição                                                                                                                                                                                                                                                                     | Ação                                                                                                                                                                                            |
| ------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [payment_intent.succeeded](https://docs.stripe.com/api/events/types.md?lang=php#event_types-payment_intent.succeeded)           | Enviado quando um cliente conclui um pagamento com êxito.                                                                                                                                                                                                                     | Envie ao cliente uma confirmação de pedido e *processe* (Fulfillment is the process of providing the goods or services purchased by a customer, typically after payment is collected) o pedido. |
| [payment_intent.processing](https://docs.stripe.com/api/events/types.md?lang=php#event_types-payment_intent.processing)         | Enviado quando um cliente inicia um pagamento, mas o pagamento ainda precisa ser concluído. Esse evento costuma ser enviado quando um cliente inicia um débito bancário. Ele é seguido por um evento `payment_intent.succeeded` ou `payment_intent.payment_failed` no futuro. | Envie ao cliente uma confirmação do pedido que indica que o pagamento está pendente. Para produtos digitais, pode ser necessário executar o pedido antes de aguardar a conclusão do pagamento.  |
| [payment_intent.payment_failed](https://docs.stripe.com/api/events/types.md?lang=php#event_types-payment_intent.payment_failed) | Enviado quando um cliente tenta fazer um pagamento, mas o pagamento falha.                                                                                                                                                                                                    | Se um pagamento passa de `processing` para `payment_failed`, ofereça ao cliente outra tentativa para pagar.                                                                                     |

## Testar a integração

#### Cartões

| Número do cartão    | Cenário                                                                                                                                                                                                                                                                                             | Como testar                                                                                                                 |
| ------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------- |
| 4242424242424242    | O pagamento com cartão é bem-sucedido e não precisa de autenticação.                                                                                                                                                                                                                                | Preencha o formulário do cartão de crédito usando o número do cartão de crédito com qualquer validade, CVC e código postal. |
| 4000002500003155    | O pagamento com cartão precisa de *autenticação* (Strong Customer Authentication (SCA) is a regulatory requirement in effect as of September 14, 2019, that impacts many European online payments. It requires customers to use two-factor authentication like 3D Secure to verify their purchase). | Preencha o formulário do cartão de crédito usando o número do cartão de crédito com qualquer validade, CVC e código postal. |
| 4000000000009995    | O cartão é recusado com um código de recusa como `insufficient_funds`.                                                                                                                                                                                                                              | Preencha o formulário do cartão de crédito usando o número do cartão de crédito com qualquer validade, CVC e código postal. |
| 6205500000000000004 | O cartão UnionPay tem um comprimento variável de 13 a 19 dígitos.                                                                                                                                                                                                                                   | Preencha o formulário do cartão de crédito usando o número do cartão de crédito com qualquer validade, CVC e código postal. |

#### Débito bancário autenticado

| Forma de pagamento | Cenário                                                                                                                                                                                                | Como testar                                                                                                                                                                                                |
| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Bancontact, iDEAL  | Seu cliente não faz a autenticação na página de redirecionamento de uma forma de pagamento baseada em redirecionamento e notificação imediata.                                                         | Escolha qualquer forma de pagamento baseada em redirecionamento, preencha os dados obrigatórios e confirme o pagamento. Em seguida, clique em **Falhar pagamento de teste** na página de redirecionamento. |
| Pay by Bank        | O cliente paga com uma forma de pagamento baseada em redirecionamento e [notificação posterior](https://docs.stripe.com/payments/payment-methods.md#payment-notification).                             | Escolha a forma de pagamento, preencha os dados obrigatórios e confirme o pagamento. Em seguida, clique em **Concluir o pagamento de teste** na página de redirecionamento.                                |
| Pay by Bank        | Seu cliente não faz a autenticação na página de redirecionamento de uma forma de pagamento baseada em redirecionamento e notificação posterior.                                                        | Escolha a forma de pagamento, preencha os dados obrigatórios e confirme o pagamento. Em seguida, clique em **Falhar o pagamento de teste** na página de redirecionamento.                                  |
| BLIK               | Os pagamentos BLIK falham de várias formas: falhas imediatas (por exemplo, o código está vencido ou inválido), erros atrasados (o banco recusa) ou limites de tempo (o cliente não respondeu a tempo). | Use padrões de e-mail para [simular as diferentes falhas.](https://docs.stripe.com/payments/blik/accept-a-payment.md#simulate-failures)                                                                    |

#### Débitos bancários

| Forma de pagamento     | Cenário                                                                                           | Como testar                                                                                                                                                                     |
| ---------------------- | ------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Débito automático SEPA | O cliente paga com débito automático SEPA.                                                        | Preencha o formulário usando o número de conta `AT321904300235473204`. Inicialmente, o status do PaymentIntent muda para processando e, três minutos depois, para bem-sucedido. |
| Débito automático SEPA | O status da intenção de pagamento do cliente muda de `processing` para `requires_payment_method`. | Preencha o formulário usando o número de conta `AT861904300235473202`.                                                                                                          |

Consulte [Testes](https://docs.stripe.com/testing.md) para obter mais informações sobre como testar sua integração.

## Optional: Habilitar Apple Pay

> Se sua tela de checkout tiver um **botão Apple Pay** exclusivo, siga o [guia do Apple Pay](https://docs.stripe.com/apple-pay.md#present-payment-sheet) e use `ApplePayContext` para receber pagamentos pelo botão Apple Pay. Você pode usar `PaymentSheet` para processar outros tipos de forma de pagamento.

### Solicitar um ID de comerciante da Apple

Obtenha um ID de comerciante da Apple [solicitando um novo identificador](https://developer.apple.com/account/resources/identifiers/add/merchant) no site de desenvolvedores da Apple.

Preencha o formulário com descrição e identificador. A descrição é para seu controle e pode ser modificada no futuro. A Stripe recomenda que você use o nome do aplicativo como identificador (por exemplo, `merchant.com.{{YOUR_APP_NAME}}`).

### Criar um certificado Apple Pay

Crie um certificado para criptografia de dados de pagamento pelo aplicativo.

Vá até [Configurações de certificado do iOS](https://dashboard.stripe.com/settings/ios_certificates) no Dashboard, clique em **Adicionar novo aplicativo** e siga o guia.

Baixe um arquivo de solicitação de assinatura de certificado (CSR) para obter um certificado seguro da Apple que permite usar o Apple Pay.

Um arquivo CSR deve ser usado para emitir exatamente um certificado. Se você trocar seu ID de comerciante da Apple, acesse as [Configurações de certificado do iOS](https://dashboard.stripe.com/settings/ios_certificates) no Dashboard para obter um novo CSR e certificado.

### Integrar com Xcode

Adicione as funções do Apple Pay ao aplicativo. No Xcode, abra as configurações do projeto, clique na guia **Signing & Capabilities** e adicione o recurso **Apple Pay**. Talvez seja necessário fazer login na sua conta de desenvolvedor. Selecione o ID de comerciante criado anteriormente e o aplicativo já pode aceitar Apple Pay.
![](https://b.stripecdn.com/docs-statics-srv/assets/xcode.a701d4c1922d19985e9c614a6f105bf1.png)

Habilitar o recurso Apple Pay no Xcode

### Adicionar Apple Pay

#### Pagamento avulso

Para adicionar Apple Pay à PaymentSheet, defina [applePay](https://stripe.dev/stripe-ios/stripe-paymentsheet/Classes/PaymentSheet/Configuration.html#/s:6Stripe12PaymentSheetC13ConfigurationV8applePayAC05ApplefD0VSgvp) após inicializar `PaymentSheet.Configuration` com seu ID de comerciante Apple e o [código de país da sua empresa](https://dashboard.stripe.com/settings/account).

#### iOS (Swift)

```swift
var configuration = PaymentSheet.Configuration()
configuration.applePay = .init(
  merchantId: "merchant.com.your_app_name",
  merchantCountryCode: "US"
)
```

#### Pagamentos recorrentes

Para adicionar Apple Pay à PaymentSheet, defina [applePay](https://stripe.dev/stripe-ios/stripe-paymentsheet/Classes/PaymentSheet/Configuration.html#/s:6Stripe12PaymentSheetC13ConfigurationV8applePayAC05ApplefD0VSgvp) após inicializar `PaymentSheet.Configuration` com seu ID de comerciante Apple e o [código de país da sua empresa](https://dashboard.stripe.com/settings/account).

De acordo com as [diretrizes da Apple](https://developer.apple.com/design/human-interface-guidelines/apple-pay#Supporting-subscriptions) para pagamentos recorrentes, você também precisará definir atributos adicionais no `PKPaymentRequest`. Adicione um gerenciador em [ApplePayConfiguration.paymentRequestHandlers](https://stripe.dev/stripe-ios/stripepaymentsheet/documentation/stripepaymentsheet/paymentsheet/applepayconfiguration/handlers/paymentrequesthandler) para configurar [PKPaymentRequest.paymentSummaryItems](https://developer.apple.com/documentation/passkit/pkpaymentrequest/1619231-paymentsummaryitems) com o valor que você pretende cobrar (por exemplo, 9,95&nbsp;USD por mês).

Você também pode adotar [tokens de comerciante](https://developer.apple.com/apple-pay/merchant-tokens/) definindo as propriedades `recurringPaymentRequest` ou `automaticReloadPaymentRequest` no `PKPaymentRequest`.

Para saber mais sobre como usar pagamentos recorrentes com o Apple Pay, consulte a [documentação do PassKit da Apple](https://developer.apple.com/documentation/passkit/pkpaymentrequest).

#### iOS (Swift)

```swift
let customHandlers = PaymentSheet.ApplePayConfiguration.Handlers(
    paymentRequestHandler: { request in
        // PKRecurringPaymentSummaryItem is available on iOS 15 or later
        if #available(iOS 15.0, *) {
            let billing = PKRecurringPaymentSummaryItem(label: "My Subscription", amount: NSDecimalNumber(string: "59.99"))

            // Payment starts today
            billing.startDate = Date()

            // Payment ends in one year
            billing.endDate = Date().addingTimeInterval(60 * 60 * 24 * 365)

            // Pay once a month.
            billing.intervalUnit = .month
            billing.intervalCount = 1

            // recurringPaymentRequest is only available on iOS 16 or later
            if #available(iOS 16.0, *) {
                request.recurringPaymentRequest = PKRecurringPaymentRequest(paymentDescription: "Recurring",
                                                                            regularBilling: billing,
                                                                            managementURL: URL(string: "https://my-backend.example.com/customer-portal")!)
                request.recurringPaymentRequest?.billingAgreement = "You'll be billed $59.99 every month for the next 12 months. To cancel at any time, go to Account and click 'Cancel Membership.'"
            }
            request.paymentSummaryItems = [billing]
            request.currencyCode = "USD"
        } else {
            // On older iOS versions, set alternative summary items.
            request.paymentSummaryItems = [PKPaymentSummaryItem(label: "Monthly plan starting July 1, 2022", amount: NSDecimalNumber(string: "59.99"), type: .final)]
        }
        return request
    }
)
var configuration = PaymentSheet.Configuration()
configuration.applePay = .init(merchantId: "merchant.com.your_app_name",
                                merchantCountryCode: "US",
                                customHandlers: customHandlers)
```

### Rastreamento de pedidos

Para adicionar informações de [rastreamento de pedidos](https://developer.apple.com/design/human-interface-guidelines/technologies/wallet/designing-order-tracking) no iOS&nbsp;16 ou posterior, configure um [authorizationResultHandler](https://stripe.dev/stripe-ios/stripepaymentsheet/documentation/stripepaymentsheet/paymentsheet/applepayconfiguration/handlers/authorizationresulthandler) em seu `PaymentSheet.ApplePayConfiguration.Handlers`. A Stripe invoca sua implementação após a conclusão do pagamento, mas antes que o iOS descarte a descrição Apple Pay.

Na sua implementação de `authorizationResultHandler`, obtenha os detalhes do pedido a partir do seu servidor para o pedido concluído. Adicione esses detalhes ao [PKPaymentAuthorizationResult](https://developer.apple.com/documentation/passkit/pkpaymentauthorizationresult) fornecido e retorne o resultado modificado.

Para saber mais sobre o rastreamento de pedidos, consulte a [documentação de pedidos da carteira da Apple](https://developer.apple.com/documentation/walletorders).

#### iOS (Swift)

```swift
let customHandlers = PaymentSheet.ApplePayConfiguration.Handlers(
    authorizationResultHandler: { result in
      do {
        // Fetch the order details from your service
        let myOrderDetails = try await MyAPIClient.shared.fetchOrderDetails(orderID: orderID)
        result.orderDetails = PKPaymentOrderDetails(
          orderTypeIdentifier: myOrderDetails.orderTypeIdentifier, // "com.myapp.order"
          orderIdentifier: myOrderDetails.orderIdentifier, // "ABC123-AAAA-1111"
          webServiceURL: myOrderDetails.webServiceURL, // "https://my-backend.example.com/apple-order-tracking-backend"
          authenticationToken: myOrderDetails.authenticationToken) // "abc123"
        // Return your modified PKPaymentAuthorizationResult
        return result
      } catch {
        return PKPaymentAuthorizationResult(status: .failure, errors: [error])
      }
    }
)
var configuration = PaymentSheet.Configuration()
configuration.applePay = .init(merchantId: "merchant.com.your_app_name",
                               merchantCountryCode: "US",
                               customHandlers: customHandlers)
```

## Habilitar leitura de cartões

Para habilitar o suporte à leitura de cartões no iOS, defina `NSCameraUsageDescription` (**Privacy - Camera Usage Description**) no `Info.plist` do seu aplicativo e informe um motivo para o acesso à câmera (por exemplo, “Para ler cartões”).

## Optional: Personalizar a descrição

Toda personalização é configurada usando o objeto [PaymentSheet.Configuration](https://stripe.dev/stripe-ios/stripe-paymentsheet/Classes/PaymentSheet/Configuration.html).

### Aparência

Personalize cores, fontes e assim por diante para combinar com a aparência do seu aplicativo usando a [API appearance](https://docs.stripe.com/elements/appearance-api/mobile.md?platform=ios).

### Layout da forma de pagamento

Configure o layout das formas de pagamento na planilha usando [paymentMethodLayout](https://stripe.dev/stripe-ios/stripepaymentsheet/documentation/stripepaymentsheet/paymentsheet/configuration-swift.struct/paymentmethodlayout). Você pode exibi-los horizontalmente, verticalmente ou deixar a Stripe otimizar o layout automaticamente.
![](https://b.stripecdn.com/docs-statics-srv/assets/ios-mpe-payment-method-layouts.9d0513e2fcec5660378ba1824d952054.png)

#### Swift

```swift
var configuration = PaymentSheet.Configuration()
configuration.paymentMethodLayout = .automatic
```

### Coletar endereços de usuários

Colete endereços de entrega ou cobrança locais e internacionais de seus clientes usando o [Address Element](https://docs.stripe.com/elements/address-element.md?platform=ios).

### Nome de exibição do comerciante

Especifique o nome da empresa exibido para o cliente definindo [merchantDisplayName](https://stripe.dev/stripe-ios/stripe-paymentsheet/Classes/PaymentSheet/Configuration.html#/s:18StripePaymentSheet0bC0C13ConfigurationV19merchantDisplayNameSSvp). Por padrão, esse é o nome do seu aplicativo.

#### Swift

```swift
var configuration = PaymentSheet.Configuration()
configuration.merchantDisplayName = "My app, Inc."
```

### Modo escuro

A `PaymentSheet` se adapta automaticamente às configurações de aparência do sistema do usuário (modos claro e escuro). Se o seu aplicativo não aceitar o modo escuro, defina [estilo](https://stripe.dev/stripe-ios/stripe-paymentsheet/Classes/PaymentSheet/Configuration.html#/s:18StripePaymentSheet0bC0C13ConfigurationV5styleAC18UserInterfaceStyleOvp) como modo `alwaysLight` ou `alwaysDark`.

```swift
var configuration = PaymentSheet.Configuration()
configuration.style = .alwaysLight
```

### Dados de faturamento padrão

Para definir valores padrão para dados de faturamento coletados na descrição da compra, configure a propriedade `defaultBillingDetails`. A `PaymentSheet` preenche previamente seus campos com os valores que você informou.

```swift
var configuration = PaymentSheet.Configuration()
configuration.defaultBillingDetails.address.country = "US"
configuration.defaultBillingDetails.email = "foo@bar.com"
```

### Coleta de dados de faturamento

Use `billingDetailsCollectionConfiguration` para especificar como você deseja coletar dados de faturamento na página de pagamento.

Você pode coletar o nome, e-mail, número de telefone e endereço do cliente.

Se você quiser apenas os dados de faturamento exigidos pela forma de pagamento, defina `billingDetailsCollectionConfiguration.attachDefaultsToPaymentMethod` como verdadeiro. Nesse caso, `PaymentSheet.Configuration.defaultBillingDetails` são definidos como os [detalhes de faturamento](https://docs.stripe.com/api/payment_methods/object.md?lang=node#payment_method_object-billing_details) da forma de pagamento.

Se você quiser coletar dados de faturamento adicionais que não são necessariamente exigidos pela forma de pagamento, defina `billingDetailsCollectionConfiguration.attachDefaultsToPaymentMethod` como falso. Nesse caso, os dados de faturamento coletados por meio da `PaymentSheet` são definidos como os dados de faturamento da forma de pagamento.

```swift
var configuration = PaymentSheet.Configuration()
configuration.defaultBillingDetails.email = "foo@bar.com"
configuration.billingDetailsCollectionConfiguration.name = .always
configuration.billingDetailsCollectionConfiguration.email = .never
configuration.billingDetailsCollectionConfiguration.address = .full
configuration.billingDetailsCollectionConfiguration.attachDefaultsToPaymentMethod = true
```

> Consulte seu jurídico sobre as leis que se aplicam à coleta de dados. Só colete números de telefone se precisar deles para a transação.

## Optional: Conclua o pagamento em sua IU

Você pode exibir o Payment Sheet apenas para coletar dados da forma de pagamento e depois chamar um método `confirm` para concluir o pagamento na IU do aplicativo. Isso é útil quando você tem um botão de compra personalizado ou precisa de mais etapas após a coleta dos dados do pagamento.
![](https://b.stripecdn.com/docs-statics-srv/assets/ios-multi-step.cd631ea4f1cd8cf3f39b6b9e1e92b6c5.png)

Conclua o pagamento na IU do aplicativo

#### UIKit

As etapas a seguir mostram como concluir o pagamento na IU do aplicativo. Veja nosso exemplo de integração no [GitHub](https://github.com/stripe/stripe-ios/blob/master/Example/PaymentSheet%20Example/PaymentSheet%20Example/ExampleCustomCheckoutViewController.swift).

1. Primeiro, inicialize [PaymentSheet.FlowController](https://stripe.dev/stripe-ios/stripepaymentsheet/documentation/stripepaymentsheet/paymentsheet/flowcontroller) em vez de `PaymentSheet` e atualize a IU com sua propriedade `paymentOption`. Essa propriedade contém uma imagem e um rótulo que representam a forma de pagamento padrão selecionada inicialmente pelo cliente.

```swift
PaymentSheet.FlowController.create(paymentIntentClientSecret: paymentIntentClientSecret, configuration: configuration) { [weak self] result in
  switch result {
  case .failure(let error):
    print(error)
  case .success(let paymentSheetFlowController):
    self?.paymentSheetFlowController = paymentSheetFlowController
    // Update your UI using paymentSheetFlowController.paymentOption
  }
}
```

1. Em seguida, chame `presentPaymentOptions` para coletar os detalhes do pagamento. Quando terminar, atualize sua IU novamente com a propriedade `paymentOption`.

```swift
paymentSheetFlowController.presentPaymentOptions(from: self) {
  // Update your UI using paymentSheetFlowController.paymentOption
}
```

1. Por fim, chame `confirm`.

```swift
paymentSheetFlowController.confirm(from: self) { paymentResult in
  // MARK: Handle the payment result
  switch paymentResult {
  case .completed:
    print("Payment complete!")
  case .canceled:
    print("Canceled!")
  case .failed(let error):
    print(error)
  }
}
```

#### SwiftUI

As etapas a seguir mostram como concluir o pagamento na IU do aplicativo. Veja nosso exemplo de integração no [GitHub](https://github.com/stripe/stripe-ios/blob/master/Example/PaymentSheet%20Example/PaymentSheet%20Example/ExampleSwiftUICustomPaymentFlow.swift).

1. Primeiro, inicialize [PaymentSheet.FlowController](https://stripe.dev/stripe-ios/stripepaymentsheet/documentation/stripepaymentsheet/paymentsheet/flowcontroller) em vez de `PaymentSheet`. A propriedade `paymentOption` contém uma imagem e um rótulo representando a forma de pagamento selecionada no momento pelo cliente, que você pode usar na sua IU.

```swift
PaymentSheet.FlowController.create(paymentIntentClientSecret: paymentIntentClientSecret, configuration: configuration) { [weak self] result in
  switch result {
  case .failure(let error):
    print(error)
  case .success(let paymentSheetFlowController):
    self?.paymentSheetFlowController = paymentSheetFlowController
    // Use the paymentSheetFlowController.paymentOption properties in your UI
    myPaymentMethodLabel = paymentSheetFlowController.paymentOption?.label ?? "Select a payment method"
    myPaymentMethodImage = paymentSheetFlowController.paymentOption?.image ?? UIImage(systemName: "square.and.pencil")!
  }
}
```

1. Use [PaymentSheet.FlowController.PaymentOptionsButton](https://stripe.dev/stripe-ios/stripepaymentsheet/documentation/stripepaymentsheet/paymentsheet/flowcontroller/paymentoptionsbutton) para inserir o botão que apresenta a descrição da compra para coletar os dados de pagamento. Quando `PaymentSheet.FlowController` chama o argumento `onSheetDismissed`, o `paymentOption` da instância `PaymentSheet.FlowController` reflete a forma de pagamento selecionada.

```swift
PaymentSheet.FlowController.PaymentOptionsButton(
  paymentSheetFlowController: paymentSheetFlowController,
  onSheetDismissed: {
    myPaymentMethodLabel = paymentSheetFlowController.paymentOption?.label ?? "Select a payment method"
    myPaymentMethodImage = paymentSheetFlowController.paymentOption?.image ?? UIImage(systemName: "square.and.pencil")!
  },
  content: {
    /* An example button */
    HStack {
      Text(myPaymentMethodLabel)
      Image(uiImage: myPaymentMethodImage)
    }
  }
)
```

1. Use [PaymentSheet.FlowController.PaymentOptionsButton](https://stripe.dev/stripe-ios/stripepaymentsheet/documentation/stripepaymentsheet/paymentsheet/flowcontroller/paymentoptionsbutton) para encapsular o botão que confirma o pagamento.

```swift
PaymentSheet.FlowController.ConfirmButton(
  paymentSheetFlowController: paymentSheetFlowController,
  onCompletion: { result in
    // MARK: Handle the payment result
    switch result {
    case .completed:
      print("Payment complete!")
    case .canceled:
      print("Canceled!")
    case .failed(let error):
      print(error)
    }
  },
  content: {
    /* An example button */
    Text("Pay")
  }
)
```

Se `PaymentSheetResult` for `.completed`, informe ao cliente, por exemplo, exibindo uma tela de confirmação do pedido.

Configurar `allowsDelayedPaymentMethods` como verdadeiro permite formas de pagamento de [notificação assíncrona](https://docs.stripe.com/payments/payment-methods.md#payment-notification) 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.


# Somente Element Card

> This is a Somente Element Card for when platform is ios and mobile-ui is card-element. View the full page at https://docs.stripe.com/connect/end-to-end-marketplace?platform=ios&mobile-ui=card-element.

Colete dados de cartões com segurança usando [STPPaymentCardTextField](https://stripe.dev/stripe-ios/stripe-payments-ui/Classes/STPPaymentCardTextField.html), um componente de IU inserível fornecido pelo SDK que coleta o número do cartão, a data de validade, o CVC e o código postal.
![](https://d37ugbyn3rpeym.cloudfront.net/docs/mobile/ios/card-field.mp4)
Este guia mostra como aceitar pagamentos e movimentar fundos para as contas bancárias dos seus vendedores ou prestadores de serviços. Para fins de demonstração, criaremos um marketplace de locações residenciais que conecta proprietários a pessoas que querem alugar um imóvel. Você pode usar os conceitos deste guia para outras situações.

## Pré-requisitos

1. [Cadastre sua plataforma](https://dashboard.stripe.com/connect).
1. [Verifique e adicione os dados da empresa no Dashboard](https://dashboard.stripe.com/account/onboarding).
1. [Conclua seu perfil da plataforma](https://dashboard.stripe.com/connect/settings/profile).
1. [Personalize as configurações da sua marca](https://dashboard.stripe.com/settings/connect/stripe-dashboard/branding). Adicione um nome de empresa, ícone e cor da marca.

## Configurar a Stripe [Lado do servidor] [Lado do cliente]

Primeiro, você precisa de uma conta Stripe. [Inscreva-se aqui](https://dashboard.stripe.com/register).

### Lado do servidor

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

#### Ruby

```bash
# Available as a gem
sudo gem install stripe
```

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

### Lado do cliente

O [SDK da Stripe para iOS](https://github.com/stripe/stripe-ios) é de código aberto, [totalmente documentado](https://stripe.dev/stripe-ios/index.html) e compatível com aplicativos que aceitam iOS 13 ou versões mais recentes.

#### Gerenciador de pacotes Swift

Para instalar o SDK, siga estas etapas:

1. No Xcode, selecione **Arquivo** > **Adicionar dependências de pacote…** e insira `https://github.com/stripe/stripe-ios-spm` como URL do repositório.
1. Selecione o número da última versão da nossa [página de lançamentos](https://github.com/stripe/stripe-ios/releases).
1. Adicione o produto **StripePaymentsUI** ao [alvo do seu aplicativo](https://developer.apple.com/documentation/swift_packages/adding_package_dependencies_to_your_app).

#### CocoaPods

1. Se ainda não o fez, instale a versão mais recente do [CocoaPods](https://guides.cocoapods.org/using/getting-started.html).
1. Se não tiver um [Podfile](https://guides.cocoapods.org/syntax/podfile.html), execute o seguinte comando para criar um:
   ```bash
   pod init
   ```
1. Adicione esta linha ao seu `Podfile`:
   ```podfile
   pod 'StripePaymentsUI'
   ```
1. Execute o seguinte comando:
   ```bash
   pod install
   ```
1. Não se esqueça de usar o arquivo `.xcworkspace` para abrir seu projeto em Xcode, em vez do arquivo `.xcodeproj`, daqui em diante.
1. No futuro, para atualizar para a versão mais recente do SDK, execute:
   ```bash
   pod update StripePaymentsUI
   ```

#### Carthage

1. Se ainda não o fez, instale a versão mais recente do [Carthage](https://github.com/Carthage/Carthage#installing-carthage).
1. Adicione esta linha ao seu `Cartfile`:
   ```cartfile
   github "stripe/stripe-ios"
   ```
1. Siga as [instruções de instalação do Carthage](https://github.com/Carthage/Carthage#if-youre-building-for-ios-tvos-or-watchos). Certifique-se de integrar todas as estruturas necessárias listadas [here](https://github.com/stripe/stripe-ios/tree/master/StripePaymentsUI/README.md#manual-linking).
1. No futuro, para atualizar para a versão mais recente do SDK, execute o seguinte comando:
   ```bash
   carthage update stripe-ios --platform ios
   ```

#### Estrutura manual

1. Vá até a nossa [página de lançamentos do GitHub](https://github.com/stripe/stripe-ios/releases/latest) e baixe e descompacte o **Stripe.xcframework.zip**.
1. Arraste **StripePaymentsUI.xcframework** até a seção **Embedded Binaries** das configurações **General** no seu projeto Xcode. Certifique-se de selecionar **Copy items if needed**.
1. Repita a etapa 2 para todas as estruturas necessárias listadas [here](https://github.com/stripe/stripe-ios/tree/master/StripePaymentsUI/README.md#manual-linking).
1. No futuro, para atualizar para a versão mais recente do nosso SDK, repita as etapas 1 a 3.

> Para obter mais informações sobre a versão mais recente e as versões anteriores do SDK, consulte a página [Lançamentos](https://github.com/stripe/stripe-ios/releases) no GitHub. Para receber notificações quando um novo lançamento for publicado, [assista aos lançamentos](https://help.github.com/en/articles/watching-and-unwatching-releases-for-a-repository#watching-releases-for-a-repository) do repositório.

Configure o SDK com sua [chave publicável da Stripe](https://dashboard.stripe.com/test/apikeys) na inicialização do aplicativo. Isso permite que seu aplicativo faça solicitações à API da Stripe .

#### Swift

```swift
import UIKitimportStripePaymentsUI

@main
class AppDelegate: UIResponder, UIApplicationDelegate {

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

> Use suas [chaves de teste](https://docs.stripe.com/keys.md#obtain-api-keys) enquanto testa e desenvolve, e suas chaves de [modo de produção](https://docs.stripe.com/keys.md#test-live-modes) quando publicar seu aplicativo.

## Criar uma conta conectada

#### Accounts v2

Quando um vendedor ou provedor de serviços se cadastra na sua plataforma, crie uma [conta conectada](https://docs.stripe.com/api/v2/core/accounts.md) que o represente. A conta conectada permite que você recolha suas informações de identificação, aceite pagamentos para eles e transfira fundos para a conta bancária deles. Em nosso exemplo de aluguel de casas, a conta conectada representa o proprietário da casa.

#### Accounts v1

Quando um vendedor ou provedor de serviços se cadastra na sua plataforma, crie uma [conta conectada](https://docs.stripe.com/api/accounts.md) que o represente. A conta conectada permite que você recolha suas informações de identificação, aceite pagamentos para eles e transfira fundos para a conta bancária deles. Em nosso exemplo de aluguel de casas, a conta conectada representa o proprietário da casa.
![](https://b.stripecdn.com/docs-statics-srv/assets/express-ios.6789c3d9f8e327847abb218d75a29eec.png)

> Este guia usa contas Express com determinadas [restrições](https://docs.stripe.com/connect/express-accounts.md#prerequisites-for-using-express). Você também tem a opção de avaliar [contas Custom](https://docs.stripe.com/connect/custom-accounts.md).

### Crie uma conta conectada com informações pré-preenchidas

#### Accounts v2

Use a API `/v2/core/accounts` para [criar](https://docs.stripe.com/api/v2/core/accounts/create.md) uma conta conectada, especificando o [dashboard da conta conectada e as responsabilidades](https://docs.stripe.com/connect/accounts-v2/connected-account-configuration.md).

```curl
curl -X POST https://api.stripe.com/v2/core/accounts \
  -H "Authorization: Bearer <<YOUR_SECRET_KEY>>" \
  -H "Stripe-Version: 2026-01-28.clover" \
  --json '{
    "contact_email": "furever_contact@example.com",
    "display_name": "Furever",
    "defaults": {
        "responsibilities": {
            "fees_collector": "application",
            "losses_collector": "application"
        }
    },
    "dashboard": "express",
    "identity": {
        "business_details": {
            "registered_name": "Furever"
        },
        "country": "us",
        "entity_type": "company"
    },
    "configuration": {
        "merchant": {
            "capabilities": {
                "card_payments": {
                    "requested": true
                }
            }
        },
        "recipient": {
            "capabilities": {
                "stripe_balance": {
                    "stripe_transfers": {
                        "requested": true
                    }
                }
            }
        }
    },
    "include": [
        "configuration.merchant",
        "configuration.recipient",
        "identity",
        "requirements"
    ]
  }'
```

Se você já coletou dados de suas contas conectadas, pode usá-los para preencher o objeto `Account`. Você pode preencher quaisquer dados de conta, inclusive dados pessoais e comerciais, dados de contas externas e muito mais.

Após criar uma `Conta`, crie uma [Pessoa](https://docs.stripe.com/api/v2/core/persons/create.md) para representar a pessoa responsável por abrir a conta, definindo como verdadeiro `relationship.representative` e todas as informações da conta que você queira preencher previamente (por exemplo, o nome e sobrenome).

```curl
curl -X POST https://api.stripe.com/v2/core/accounts/{{ACCOUNT_ID}}/persons \
  -H "Authorization: Bearer <<YOUR_SECRET_KEY>>" \
  -H "Stripe-Version: 2026-04-22.preview" \
  --json '{
    "given_name": "Jenny",
    "surname": "Rosen",
    "email": "jenny.rosen@example.com",
    "relationship": {
        "representative": true
    }
  }'
```

O Connect Onboarding não solicita as informações pré-preenchidas. No entanto, ele solicita que o titular da conta confirme as informações pré-preenchidas antes de aceitar o [contrato de serviços do Connect](https://docs.stripe.com/connect/service-agreement-types.md).

Ao testar sua integração, preencha antecipadamente os dados da conta usando [dados de teste](https://docs.stripe.com/connect/testing.md).

### Criar um link da conta

Você pode criar um link de conta chamando a API [Account Links v2](https://docs.stripe.com/api/v2/core/account-links.md) com os seguintes parâmetros:

- `account`
- `refresh_url`
- `return_url`
- `type` = `account_onboarding`
- `configurations` = `recipient` e `merchant`

```curl
curl -X POST https://api.stripe.com/v2/core/account_links \
  -H "Authorization: Bearer <<YOUR_SECRET_KEY>>" \
  -H "Stripe-Version: 2025-08-27.preview" \
  --json '{
    "account": "{{CONNECTEDACCOUNT_ID}}",
    "use_case": {
        "type": "account_onboarding",
        "account_onboarding": {
            "configurations": [
                "recipient",
                "merchant"
            ],
            "refresh_url": "https://example.com/reauth",
            "return_url": "https://example.com/return"
        }
    }
  }'
```

### Redirecionar o usuário ao URL do link da conta

A resposta de criação do link da conta inclui um valor de `url`. Após autenticar o usuário no seu aplicativo, redirecione-o para essa URL para inseri-lo no fluxo. As URLs de link da conta são temporárias e de uso único, pois concedem acesso às informações pessoais do usuário da conta conectada. Se desejar preencher previamente as informações, deverá preencher antes de gerar o link da conta. Depois de criar o link da conta, não será possível ler nem gravar informações na conta conectada.

> Não envie URLs de links de conta por e-mail, SMS ou outra maneira para fora do aplicativo da sua plataforma. Em vez disso, forneça-os ao titular da conta autenticado dentro do seu aplicativo.

#### Item 1

#### Swift

```swift
import UIKit
import SafariServices

let BackendAPIBaseURL: String = "" // Set to the URL of your backend server

class ConnectOnboardViewController: UIViewController {

    // ...

    override func viewDidLoad() {
        super.viewDidLoad()

        let connectWithStripeButton = UIButton(type: .system)
        connectWithStripeButton.setTitle("Connect with Stripe", for: .normal)
        connectWithStripeButton.addTarget(self, action: #selector(didSelectConnectWithStripe), for: .touchUpInside)
        view.addSubview(connectWithStripeButton)

        // ...
    }

    @objc
    func didSelectConnectWithStripe() {
        if let url = URL(string: BackendAPIBaseURL)?.appendingPathComponent("onboard-user") {
          var request = URLRequest(url: url)
          request.httpMethod = "POST"
          let task = URLSession.shared.dataTask(with: request) { (data, response, error) in
              guard let data = data,
                  let json = try? JSONSerialization.jsonObject(with: data, options: []) as? [String : Any],
                  let accountURLString = json["url"] as? String,
                  let accountURL = URL(string: accountURLString) else {
                      // handle error
              }

              let safariViewController = SFSafariViewController(url: accountURL)
              safariViewController.delegate = self

              DispatchQueue.main.async {
                  self.present(safariViewController, animated: true, completion: nil)
              }
          }
        }
    }

    // ...
}

extension ConnectOnboardViewController: SFSafariViewControllerDelegate {
    func safariViewControllerDidFinish(_ controller: SFSafariViewController) {
        // the user may have closed the SFSafariViewController instance before a redirect
        // occurred. Sync with your backend to confirm the correct state
    }
}

```

#### Item 2

```xml
<?xml version="1.0" encoding="utf-8"?>
<androidx.constraintlayout.widget.ConstraintLayout
    xmlns:android="http://schemas.android.com/apk/res/android"
    xmlns:app="http://schemas.android.com/apk/res-auto"
    xmlns:tools="http://schemas.android.com/tools"
    android:layout_width="match_parent"
    android:layout_height="match_parent"
    tools:context=".activity.ConnectWithStripeActivity">

    <Button
        android:id="@+id/connect_with_stripe"
        android:text="Connect with Stripe"
        android:layout_height="wrap_content"
        android:layout_width="wrap_content"
        app:layout_constraintBottom_toBottomOf="parent"
        app:layout_constraintEnd_toEndOf="parent"
        app:layout_constraintStart_toStartOf="parent"
        app:layout_constraintTop_toTopOf="parent"
        style="?attr/materialButtonOutlinedStyle"
        />

</androidx.constraintlayout.widget.ConstraintLayout>
```

#### Kotlin

```kotlin
class ConnectWithStripeActivity : AppCompatActivity() {

    private val viewBinding: ActivityConnectWithStripeViewBinding by lazy {
        ActivityConnectWithStripeViewBinding.inflate(layoutInflater)
    }
    private val httpClient = OkHttpClient()

    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        setContentView(viewBinding.root)

        viewBinding.connectWithStripe.setOnClickListener {
            val weakActivity = WeakReference<Activity>(this)
            val request = Request.Builder()
                .url(BACKEND_URL + "onboard-user")
                .post("".toRequestBody())
                .build()
            httpClient.newCall(request)
                .enqueue(object: Callback {
                    override fun onFailure(call: Call, e: IOException) {
                        // Request failed
                    }
                    override fun onResponse(call: Call, response: Response) {
                        if (!response.isSuccessful) {
                            // Request failed
                        } else {
                            val responseData = response.body?.string()
                            val responseJson =
                                responseData?.let { JSONObject(it) } ?: JSONObject()
                            val url = responseJson.getString("url")

                            weakActivity.get()?.let {
                                val builder: CustomTabsIntent.Builder = CustomTabsIntent.Builder()
                                val customTabsIntent = builder.build()
                                customTabsIntent.launchUrl(it, Uri.parse(url))
                            }
                        }
                    }
                })
        }
    }

    internal companion object {
        internal const val BACKEND_URL = "https://example-backend-url.com/"
    }
}
```

#### Item 3

### Gerenciar o usuário que volta à plataforma

O Connect Onboarding exige que você passe tanto um `return_url` quanto um `refresh_url` para lidar com todos os casos em que o usuário da conta é redirecionado para a sua plataforma.

> Você pode usar HTTP para seu `return_url` e para o `refresh_url` enquanto estiver em um ambiente de teste (por exemplo, para testar com o localhost), mas modo de produção aceita apenas HTTPS. Você deve atualizar URLs de teste para URLs HTTPS antes do lançamento.

#### return_url

A Stripe emite um redirecionamento para essa URL quando o usuário da conta conectada conclui o fluxo de onboarding. Isso não significa que todas as informações tenham sido recolhidas ou que não haja requisitos pendentes na conta. Significa apenas que o fluxo foi inserido e encerrado corretamente.

Nenhum estado é transmitido por essa URL. Depois que um usuário for redirecionado para o seu `return_url`, verifique o estado dos requisitos na conta dele fazendo o seguinte:

- Ouça os Webhooks `v2.core.account[requirements].updated`.
- Chame a API [Accounts v2](https://docs.stripe.com/api/v2/core/accounts/retrieve.md) e inspecione o objeto retornado.

#### refresh_url

A Stripe redireciona seu usuário para o `refresh_url` nestes casos:

- O link expirou (alguns minutos se passaram desde a criação do link).
- O usuário já acessou o URL (atualizou a página ou clicou em Voltar ou Avançar no navegador).
- Sua plataforma não consegue mais acessar a conta.
- A conta foi recusada.

Configure sua página `refresh_url` para acionar um método em seu servidor para chamar [Account Links v2](https://docs.stripe.com/api/v2/core/account-links.md) novamente com os mesmos parâmetros e redirecionar o usuário para o novo link.

### Gerenciar usuários que não concluíram o onboarding

Um usuário redirecionado para o seu `return_url` pode não ter concluído o processo de onboarding. Use o endpoint `/v2/core/accounts` para recuperar a conta do usuário e verificar se [configuration.recipient.capabilities.stripe_balance.stripe_transfers.status](https://docs.stripe.com/api/v2/core/accounts/object.md#v2_account_object-configuration-recipient-capabilities-stripe_balance-stripe_transfers-status) está coo `active`. Se o status não estiver `active` e [configuration.destinatário.capabilities.stripe_balance.stripe_transfers.status_details.code](https://docs.stripe.com/api/v2/core/accounts/object.md#v2_account_object-configuration-recipient-capabilities-stripe_balance-stripe_transfers-status_details-code) for `requirements_past_due`, forneça prompts na IU para permitir que o usuário continue o onboarding por meio de um novo link de conta. Para outros códigos, trate-os conforme necessário.

#### Accounts v1

Use a API `/v1/accounts` para [criar](https://docs.stripe.com/api/accounts/create.md) uma conta conectada especificando as [propriedades da conta conectada](https://docs.stripe.com/connect/migrate-to-controller-properties.md) ou o tipo de conta.

```curl
curl https://api.stripe.com/v1/accounts \
  -u "<<YOUR_SECRET_KEY>>:" \
  -d "controller[losses][payments]=application" \
  -d "controller[fees][payer]=application" \
  -d "controller[stripe_dashboard][type]=express"
```

Se você já coletou dados de suas contas conectadas, pode usá-los para preencher o objeto `Account`. Você pode preencher quaisquer dados de conta, inclusive dados pessoais e comerciais, dados de contas externas e muito mais.

Depois de criar uma `Account`, crie uma [Pessoa](https://docs.stripe.com/api/persons/create.md) para representar a pessoa responsável por abrir a conta, com `relationship.representative` definido como verdadeiro e informações da conta que você queira preencher previamente (por exemplo, o nome e sobrenome).

```curl
curl https://api.stripe.com/v1/accounts/{{ACCOUNT_ID}}/persons \
  -u "<<YOUR_SECRET_KEY>>:" \
  -d first_name=Jenny \
  -d last_name=Rosen \
  -d "relationship[representative]=true"
```

O Connect Onboarding não solicita as informações pré-preenchidas. No entanto, ele solicita que o titular da conta confirme as informações pré-preenchidas antes de aceitar o [contrato de serviços do Connect](https://docs.stripe.com/connect/service-agreement-types.md).

Ao testar sua integração, preencha antecipadamente os dados da conta usando [dados de teste](https://docs.stripe.com/connect/testing.md).

### Criar um link da conta

Você pode criar um link de conta chamando a API [Account Links v1](https://docs.stripe.com/api/account_links.md) com os seguintes parâmetros:

- `account`
- `refresh_url`
- `return_url`
- `type` = `account_onboarding`

```curl
curl https://api.stripe.com/v1/account_links \
  -u "<<YOUR_SECRET_KEY>>:" \
  -d "account={{CONNECTEDACCOUNT_ID}}" \
  --data-urlencode "refresh_url=https://example.com/reauth" \
  --data-urlencode "return_url=https://example.com/return" \
  -d type=account_onboarding
```

### Redirecionar o usuário ao URL do link da conta

A resposta da criação do link da conta inclui um valor de `url`. Após autenticar o usuário no seu aplicativo, redirecione-o para esta URL para inseri-lo no fluxo. As URLs de links de conta da [API Account Links v1](https://docs.stripe.com/api/account_links.md) são temporárias e de uso único, pois concedem acesso às informações pessoais do usuário da conta conectada. Autentique o usuário no seu aplicativo antes de redirecioná-lo para esta URL. Se desejar preencher previamente as informações, deverá preencher antes de gerar o link da conta. Depois de criar o link da conta, não será possível ler nem gravar informações da conta conectada.

> Não envie URLs de links de conta por e-mail, SMS ou outra maneira para fora do aplicativo da sua plataforma. Em vez disso, forneça-os ao titular da conta autenticado dentro do seu aplicativo.

#### Item 1

#### Swift

```swift
import UIKit
import SafariServices

let BackendAPIBaseURL: String = "" // Set to the URL of your backend server

class ConnectOnboardViewController: UIViewController {

    // ...

    override func viewDidLoad() {
        super.viewDidLoad()

        let connectWithStripeButton = UIButton(type: .system)
        connectWithStripeButton.setTitle("Connect with Stripe", for: .normal)
        connectWithStripeButton.addTarget(self, action: #selector(didSelectConnectWithStripe), for: .touchUpInside)
        view.addSubview(connectWithStripeButton)

        // ...
    }

    @objc
    func didSelectConnectWithStripe() {
        if let url = URL(string: BackendAPIBaseURL)?.appendingPathComponent("onboard-user") {
          var request = URLRequest(url: url)
          request.httpMethod = "POST"
          let task = URLSession.shared.dataTask(with: request) { (data, response, error) in
              guard let data = data,
                  let json = try? JSONSerialization.jsonObject(with: data, options: []) as? [String : Any],
                  let accountURLString = json["url"] as? String,
                  let accountURL = URL(string: accountURLString) else {
                      // handle error
              }

              let safariViewController = SFSafariViewController(url: accountURL)
              safariViewController.delegate = self

              DispatchQueue.main.async {
                  self.present(safariViewController, animated: true, completion: nil)
              }
          }
        }
    }

    // ...
}

extension ConnectOnboardViewController: SFSafariViewControllerDelegate {
    func safariViewControllerDidFinish(_ controller: SFSafariViewController) {
        // the user may have closed the SFSafariViewController instance before a redirect
        // occurred. Sync with your backend to confirm the correct state
    }
}

```

#### Item 2

```xml
<?xml version="1.0" encoding="utf-8"?>
<androidx.constraintlayout.widget.ConstraintLayout
    xmlns:android="http://schemas.android.com/apk/res/android"
    xmlns:app="http://schemas.android.com/apk/res-auto"
    xmlns:tools="http://schemas.android.com/tools"
    android:layout_width="match_parent"
    android:layout_height="match_parent"
    tools:context=".activity.ConnectWithStripeActivity">

    <Button
        android:id="@+id/connect_with_stripe"
        android:text="Connect with Stripe"
        android:layout_height="wrap_content"
        android:layout_width="wrap_content"
        app:layout_constraintBottom_toBottomOf="parent"
        app:layout_constraintEnd_toEndOf="parent"
        app:layout_constraintStart_toStartOf="parent"
        app:layout_constraintTop_toTopOf="parent"
        style="?attr/materialButtonOutlinedStyle"
        />

</androidx.constraintlayout.widget.ConstraintLayout>
```

#### Kotlin

```kotlin
class ConnectWithStripeActivity : AppCompatActivity() {

    private val viewBinding: ActivityConnectWithStripeViewBinding by lazy {
        ActivityConnectWithStripeViewBinding.inflate(layoutInflater)
    }
    private val httpClient = OkHttpClient()

    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        setContentView(viewBinding.root)

        viewBinding.connectWithStripe.setOnClickListener {
            val weakActivity = WeakReference<Activity>(this)
            val request = Request.Builder()
                .url(BACKEND_URL + "onboard-user")
                .post("".toRequestBody())
                .build()
            httpClient.newCall(request)
                .enqueue(object: Callback {
                    override fun onFailure(call: Call, e: IOException) {
                        // Request failed
                    }
                    override fun onResponse(call: Call, response: Response) {
                        if (!response.isSuccessful) {
                            // Request failed
                        } else {
                            val responseData = response.body?.string()
                            val responseJson =
                                responseData?.let { JSONObject(it) } ?: JSONObject()
                            val url = responseJson.getString("url")

                            weakActivity.get()?.let {
                                val builder: CustomTabsIntent.Builder = CustomTabsIntent.Builder()
                                val customTabsIntent = builder.build()
                                customTabsIntent.launchUrl(it, Uri.parse(url))
                            }
                        }
                    }
                })
        }
    }

    internal companion object {
        internal const val BACKEND_URL = "https://example-backend-url.com/"
    }
}
```

### Gerenciar o usuário que volta à plataforma

O Connect Onboarding exige que você passe um `return_url` e `refresh_url` para gerenciar todos os casos em que o usuário é redirecionado à sua plataforma. É importante implementá-los corretamente para proporcionar a melhor experiência ao usuário.

> Você pode usar HTTP para seu `return_url` e para o `refresh_url` enquanto estiver em um ambiente de teste (por exemplo, para testar com o localhost), mas modo de produção aceita apenas HTTPS. Você deve atualizar URLs de teste para URLs HTTPS antes do lançamento.

#### return_url

A Stripe emite um redirecionamento para essa URL quando o usuário da conta conectada conclui o fluxo de onboarding. Isso não significa que todas as informações tenham sido recolhidas ou que não haja requisitos pendentes na conta. Significa apenas que o fluxo foi inserido e encerrado corretamente.

Nenhum estado é passado por este URL. Após o redirecionamento de um usuário para o `return_url` , verifique o estado do parâmetro `details_submitted` na conta dele realizando uma das seguintes ações:

- Ouça os Webhooks `account.updated`
- Chame a API [Accounts v1](https://docs.stripe.com/api/accounts.md) e inspecione o objeto retornado

#### refresh_url

A Stripe redireciona seu usuário para o `refresh_url` nestes casos:

- O link expirou (alguns minutos se passaram desde a criação do link).
- O usuário já acessou o URL (atualizou a página ou clicou em Voltar ou Avançar no navegador).
- Sua plataforma não consegue mais acessar a conta.
- A conta foi recusada.

Configure sua página `refresh_url` para acionar um método em seu servidor para chamar [Account Links v1](https://docs.stripe.com/api/account_links.md) novamente com os mesmos parâmetros e redirecionar o usuário para o novo link.

### Gerenciar usuários que não concluíram o onboarding

Um usuário que é redirecionado para seu `return_url` pode não ter concluído o processo de onboarding. Use o endpoint `/v1/accounts` para recuperar a conta do usuário e verificar se `charges_enabled`. Se a conta não estiver totalmente integrada, forneça prompts de IU para permitir que o usuário continue fazendo onboarding por meio de um novo link de conta. Você pode determinar se eles concluíram o onboarding verificando o estado do parâmetro `details_submitted` na conta deles.

## Aceitar um pagamento

### Etapa 3.1: Crie uma página de checkout (Lado do cliente)

Colete dados de cartões com segurança usando [STPPaymentCardTextField](https://stripe.dev/stripe-ios/stripe-payments-ui/Classes/STPPaymentCardTextField.html), um componente de IU inserível fornecido pelo SDK que coleta o número do cartão, a data de validade, o CVC e o código postal.
![](https://d37ugbyn3rpeym.cloudfront.net/docs/mobile/ios/card-field.mp4)
Crie uma instância do componente de cartão e um botão **Pagar**, com o seguinte código:

#### Swift

```swift
import UIKit
import StripePaymentsUI

class CheckoutViewController: UIViewController {

    lazy var cardTextField: STPPaymentCardTextField = {
        let cardTextField = STPPaymentCardTextField()
        return cardTextField
    }()
    lazy var payButton: UIButton = {
        let button = UIButton(type: .custom)
        button.layer.cornerRadius = 5
        button.backgroundColor = .systemBlue
        button.titleLabel?.font = UIFont.systemFont(ofSize: 22)
        button.setTitle("Pay", for: .normal)
        button.addTarget(self, action: #selector(pay), for: .touchUpInside)
        return button
    }()

    override func viewDidLoad() {
        super.viewDidLoad()
        view.backgroundColor = .white
        let stackView = UIStackView(arrangedSubviews: [cardTextField, payButton])
        stackView.axis = .vertical
        stackView.spacing = 20
        stackView.translatesAutoresizingMaskIntoConstraints = false
        view.addSubview(stackView)
        NSLayoutConstraint.activate([
            stackView.leftAnchor.constraint(equalToSystemSpacingAfter: view.leftAnchor, multiplier: 2),
            view.rightAnchor.constraint(equalToSystemSpacingAfter: stackView.rightAnchor, multiplier: 2),
            stackView.topAnchor.constraint(equalToSystemSpacingBelow: view.topAnchor, multiplier: 2),
        ])
    }

    @objc
    func pay() {
        // ...
    }
}
```

Execute seu aplicativo e verifique se sua página de checkout mostra o componente de cartão e o botão de pagamento.

### Etapa 3.2: Crie um PaymentIntent (Lado do servidor) (Lado do cliente)

A Stripe usa um objeto [PaymentIntent](https://docs.stripe.com/api/payment_intents.md) 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.

### Lado do servidor

No seu servidor, crie um endpoint que cria um PaymentIntent com um [valor](https://docs.stripe.com/api/payment_intents/object.md#payment_intent_object-amount) e uma [moeda](https://docs.stripe.com/api/payment_intents/object.md#payment_intent_object-currency). Sempre decida quanto deseja cobrar no lado do servidor, um ambiente confiável, e não no lado do cliente. Isso evita que clientes mal-intencionados escolham os próprios preços.

#### curl

```bash
curl https://api.stripe.com/v1/payment_intents \
  -u <<YOUR_SECRET_KEY>>: \
  -d amount=1000 \
  -d currency="usd" \
  -d "automatic_payment_methods[enabled]"=true \
  -d application_fee_amount="123" \
  -d "transfer_data[destination]"="{{CONNECTED_STRIPE_ACCOUNT_ID}}"
```

Em nosso exemplo para aluguel residencial, queremos criar uma empresa em que os clientes pagam o aluguel em nossa plataforma, e nós repassamos o aluguel aos locatários. Para configurar esta empresa:

- Indique que o aluguel é uma cobrança de destino, com `transfer_data[destination]`.
- Especifique em `application_fee_amount` o valor que será pago à plataforma.

Ao cobrar um aluguel, a Stripe transfere o valor total para o saldo em aberto da conta conectada (`transfer_data[destination]`). Em seguida, a Stripe transfere a tarifa (`application_fee_amount`) para a conta da plataforma (uma participação na receita, pela intermediação do aluguel). Por fim, são deduzidas as tarifas da Stripe do valor da tarifa da plataforma. Veja esse fluxo ilustrado abaixo:
![](https://b.stripecdn.com/docs-statics-srv/assets/application_fee_amount.837aa2339469b3c1a4319672971c1367.svg)

> Este PaymentIntent cria uma cobrança de destino. Se você quiser controlar o cronograma das transferências ou precisar transferir fundos de um único pagamento para várias partes, use [cobranças e transferências separadas](https://docs.stripe.com/connect/separate-charges-and-transfers.md).

Em vez de passar todo o objeto PaymentIntent para o seu aplicativo, retorne somente o *client secret* (The client secret is a unique key returned from Stripe as part of a PaymentIntent. This key lets the client access important fields from the PaymentIntent (status, amount, currency) while hiding sensitive ones (metadata, customer)). A chave secreta do cliente do PaymentIntent é uma chave única que permite confirmar o pagamento e atualizar dados do cartão do cliente, mas impede a manipulação de informações confidenciais, como o valor do pagamento.

### Lado do cliente

No cliente, solicite um PaymentIntent a partir do seu servidor e armazene o *segredo de cliente* (The client secret is a unique key returned from Stripe as part of a PaymentIntent. This key lets the client access important fields from the PaymentIntent (status, amount, currency) while hiding sensitive ones (metadata, customer)).

#### Swift

```swift
class CheckoutViewController: UIViewController {
    var paymentIntentClientSecret: String?

    // ...continued from previous step

    override func viewDidLoad() {
        // ...continued from previous step
        startCheckout()
    }

    func startCheckout() {
        // Request a PaymentIntent from your server and store its client secret
        // Click View full sample to see a complete implementation
    }
}
```

### Etapa 3.3: Envie o pagamento à Stripe (Lado do cliente)

Quando o cliente toca no botão **Pagar**, *confirme* (Confirming a PaymentIntent indicates that the customer intends to pay with the current or provided payment method. Upon confirmation, the PaymentIntent attempts to initiate a payment) o `PaymentIntent` para finalizar o pagamento.

Primeiro, monte um objeto [STPPaymentIntentParams](https://stripe.dev/stripe-ios/stripe-payments/Classes/STPPaymentIntentParams.html) com:

1. Os dados da forma de pagamento do campo de texto do cartão
1. O segredo do cliente do `PaymentIntent` do seu servidor

Em vez de enviar o objeto PaymentIntent para o cliente, use o *segredo do cliente* (The client secret is a unique key returned from Stripe as part of a PaymentIntent. This key lets the client access important fields from the PaymentIntent (status, amount, currency) while hiding sensitive ones (metadata, customer)), que é diferente das chaves de API que autenticam solicitações da API Stripe. O segredo do cliente é uma string que permite que o aplicativo acesse campos importantes do PaymentIntent (por exemplo, `status`), mas oculta campos confidenciais (como `customer`).

Administre cuidadosamente o segredo do cliente, pois ele pode finalizar a cobrança. Não registre em log, incorpore a URLs nem exponha esse nome a ninguém, exceto ao cliente.

Em seguida, chame o método  [STPPaymentHandler confirmPayment](https://stripe.dev/stripe-ios/stripe-payments/Classes/STPPaymentHandler.html#/c:@M@StripePayments@objc\(cs\)STPPaymentHandler\(im\)confirmPayment:withAuthenticationContext:completion:) para finalizar o pagamento.

#### Swift

```swift
class CheckoutViewController: UIViewController {

    // ...

    @objc
    func pay() {
        guard let paymentIntentClientSecret = paymentIntentClientSecret else {
            return
        }
        // Collect card details
        let paymentIntentParams = STPPaymentIntentParams(clientSecret: paymentIntentClientSecret)
        paymentIntentParams.paymentMethodParams = cardTextField.paymentMethodParams

        // Submit the payment
        let paymentHandler = STPPaymentHandler.shared()
        paymentHandler.confirmPayment(paymentIntentParams, with: self) { (status, paymentIntent, error) in
            switch (status) {
            case .failed:
                self.displayAlert(title: "Payment failed", message: error?.localizedDescription ?? "")
                break
            case .canceled:
                self.displayAlert(title: "Payment canceled", message: error?.localizedDescription ?? "")
                break
            case .succeeded:
                self.displayAlert(title: "Payment succeeded", message: paymentIntent?.description ?? "", restartDemo: true)
                break
            @unknown default:
                fatalError()
                break
            }
        }
    }
}

extension CheckoutViewController: STPAuthenticationContext {
    func authenticationPresentingViewController() -> UIViewController {
        return self
    }
}
```

Você pode [salvar os dados do cartão de pagamento de um cliente](https://docs.stripe.com/payments/payment-intents.md#future-usage) na confirmação do pagamento informando `setupFutureUsage` e um `customer` no `PaymentIntent`. Você também pode informar esses parâmetros ao criar o `PaymentIntent` no servidor.

Para informar um valor adequado em `setupFutureUsage` para o aplicativo, pode ser necessário que o cliente faça outras autenticações, mas reduz a probabilidade de recusa de pagamentos futuros pelos bancos. [Saiba como otimizar cartões para pagamentos futuros](https://docs.stripe.com/payments/payment-intents.md#future-usage) e determine qual valor usar para seu aplicativo.

| Como você pretende usar o cartão                                                                                                                                                             | Valor de enumeração `setup_future_usage` |
| -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------- |
| Somente para pagamentos *na sessão* (A payment is described as on-session if it occurs while the customer is actively in your checkout flow and able to authenticate the payment method)     | `on_session`                             |
| Somente para pagamentos *fora da sessão* (A payment is described as off-session if it occurs without the direct involvement of the customer, using previously-collected payment information) | `off_session`                            |
| Pagamentos na sessão ou fora da sessão                                                                                                                                                       | `off_session`                            |

Você pode usar um cartão configurado para pagamentos na sessão para fazer pagamentos fora da sessão, mas é mais provável que o banco recuse o pagamento fora da sessão e exija autenticação do titular do cartão.

Quando uma regulamentação como a [Autenticação Forte de Cliente](https://docs.stripe.com/strong-customer-authentication.md) exige autenticação, `STPPaymentHandler` apresenta controladores de visualização usando o [STPAuthenticationContext](https://stripe.dev/stripe-ios/stripe-payments/Protocols/STPAuthenticationContext.html) informado e orienta o cliente nesse processo. [Saiba como aceitar a autenticação do 3D Secure no iOS](https://docs.stripe.com/payments/3d-secure.md?platform=ios).

Se o pagamento é finalizado, o gerenciador de finalização é chamado com o status `.succeeded`. Caso contrário, o status é `.failed` e você pode exibir `error.localizedDescription` para o usuário.

Também é possível verificar o status de um `PaymentIntent` no [Dashboard](https://dashboard.stripe.com/test/payments) ou inspecionando a propriedade `status` no objeto.

### Etapa 3.4: Teste a integração (Lado do cliente)

​​Vários cartões de teste estão disponíveis para você usar em uma área restrita para assegurar que essa integração esteja pronta. Use-os com qualquer CVC e uma data de validade no futuro.

| Número           | Descrição                                                                                    |
| ---------------- | -------------------------------------------------------------------------------------------- |
| 4242424242424242 | Finaliza e processa o pagamento imediatamente.                                               |
| 4000002500003155 | Requer autenticação. A Stripe abre uma janela solicitando que o cliente faça a autenticação. |
| 4000000000009995 | Sempre falha, com o código de recusa `insufficient_funds`.                                   |

Veja a lista completa de cartões de teste em nosso guia de [testes](https://docs.stripe.com/testing.md).

### Etapa 3.5: Execução (Lado do servidor)

Após a conclusão do pagamento, é preciso gerenciar qualquer *execução* (Fulfillment is the process of providing the goods or services purchased by a customer, typically after payment is collected) necessária. Uma empresa de aluguel residencial que exige pagamento antecipado, por exemplo, conectaria o proprietário ao locatário após um pagamento realizado.

Configure um endpoint de *webhook* (A webhook is a real-time push notification sent to your application as a JSON payload through HTTPS requests) (para eventos *de sua conta*) [no Dashboard](https://dashboard.stripe.com/account/webhooks).
![](https://b.stripecdn.com/docs-statics-srv/assets/account_webhooks.03b71cec87ef2093fe0caa92e5bfce44.png)

Em seguida, crie um endpoint de HTTP no seu servidor para monitorar pagamentos concluídos para habilitar seus vendedores ou prestadores de serviços a processar compras. Certifique-se de substituir a chave secreta do endpoint (`whsec_...`) no exemplo com sua chave.

#### Rubi

```ruby
# Using Sinatra.
require 'sinatra'
require 'stripe'

set :port, 4242

# Don't put any keys in code. See https://docs.stripe.com/keys-best-practices.
# Find your keys at https://dashboard.stripe.com/apikeys.
client = Stripe::StripeClient.new('<<YOUR_SECRET_KEY>>')

# If you are testing your webhook locally with the Stripe CLI you
# can find the endpoint's secret by running `stripe listen`
# Otherwise, find your endpoint's secret in your webhook settings in
# the Developer Dashboard
endpoint_secret = 'whsec_...'

post '/webhook' do
  payload = request.body.read
  sig_header = request.env['HTTP_STRIPE_SIGNATURE']

  event = nil
# Verify webhook signature and extract the event.
  # See https://stripe.com/docs/webhooks#verify-events for more information.
  begin
    event = Stripe::Webhook.construct_event(
      payload, sig_header, endpoint_secret
    )
  rescue JSON::ParserError => e
    # Invalid payload.
    status 400
    return
  rescue Stripe::SignatureVerificationError => e
    # Invalid Signature.
    status 400
    return
  end

  if event['type'] == 'payment_intent.succeeded'
    payment_intent = event['data']['object']
    handle_successful_payment_intent(payment_intent)
  end

  status 200
end

def handle_successful_payment_intent(payment_intent)
  # Fulfill the purchase
  puts payment_intent.to_s
end
```

Saiba mais no nosso [guia de execução para pagamentos](https://docs.stripe.com/webhooks/handling-payment-events.md).

### Testar webhooks localmente

Use a Stripe CLI para testar webhooks localmente.

1. Primeiro [instale o Stripe CLI](https://docs.stripe.com/stripe-cli/install.md) na sua máquina, caso ainda não tenha instalado.

1. Para fazer login, execute `stripe login` na linha de comando e siga as instruções.

1. Por fim, para permitir que seu host local receba um evento simulado em sua conta conectada, execute `stripe listen --forward-to localhost:{PORT}/webhook` em uma janela do terminal e execute `stripe trigger --stripe-account={{CONNECTED_STRIPE_ACCOUNT_ID}} payment_intent.succeeded` (ou acione qualquer outro [evento aceito](https://github.com/stripe/stripe-cli/wiki/trigger-command#supported-events)) em outro.

### Etapa 3.6: Contestações

Como [comerciante de liquidação](https://docs.stripe.com/connect/destination-charges.md#settlement-merchant) das cobranças, sua plataforma é responsável pelas contestações. Leia com atenção as [práticas recomendadas](https://docs.stripe.com/disputes/responding.md) para responder a contestações.

## Testes

[Crie contas](https://docs.stripe.com/connect/testing.md#creating-accounts) e use [OAuth](https://docs.stripe.com/connect/testing.md#using-oauth) para testar o fluxo de criação de contas. É possível usar [os cartões de teste disponíveis](https://docs.stripe.com/testing.md) para testar seu fluxo de pagamentos e simular vários resultados de pagamento.


# Descrição da compra

> This is a Descrição da compra for when platform is android and mobile-ui is payment-sheet. View the full page at https://docs.stripe.com/connect/end-to-end-marketplace?platform=android&mobile-ui=payment-sheet.
![](https://b.stripecdn.com/docs-statics-srv/assets/android-overview.471eaf89a760f5b6a757fd96b6bb9b60.png)

Integre a IU de pagamento incorporada da Stripe no checkout do seu aplicativo Android com a classe [PaymentSheet](https://stripe.dev/stripe-android/paymentsheet/com.stripe.android.paymentsheet/-payment-sheet/index.html).

> #### Accounts v2 API support
> 
> The Payment Sheet doesn’t support *customer-configured Accounts* (Account configurations represent role-based functionality that you can enable for accounts, such as merchant, customer, or recipient). It only supports `Customer` objects.

Este guia mostra como aceitar pagamentos e movimentar fundos para as contas bancárias dos seus vendedores ou prestadores de serviços. Para fins de demonstração, criaremos um marketplace de locações residenciais que conecta proprietários a pessoas que querem alugar um imóvel. Você pode usar os conceitos deste guia para outras situações.

## Pré-requisitos

1. [Cadastre sua plataforma](https://dashboard.stripe.com/connect).
1. [Verifique e adicione os dados da empresa no Dashboard](https://dashboard.stripe.com/account/onboarding).
1. [Conclua seu perfil da plataforma](https://dashboard.stripe.com/connect/settings/profile).
1. [Personalize as configurações da sua marca](https://dashboard.stripe.com/settings/connect/stripe-dashboard/branding). Adicione um nome de empresa, ícone e cor da marca.

## Configurar a Stripe [Lado do servidor] [Lado do cliente]

Primeiro, você precisa de uma conta Stripe. [Inscreva-se aqui](https://dashboard.stripe.com/register).

### Lado do servidor

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

#### Ruby

```bash
# Available as a gem
sudo gem install stripe
```

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

### Lado do cliente

O [SDK da Stripe para Android](https://github.com/stripe/stripe-android) é de código aberto e [totalmente documentado](https://stripe.dev/stripe-android/).

Para instalar o SDK, adicione `stripe-android` ao bloco `dependencies` do arquivo [app/build.gradle](https://developer.android.com/studio/build/dependencies):

#### Kotlin

```kotlin
plugins {
    id("com.android.application")
}

android { ... }

dependencies {
  // ...

  // Stripe Android SDK
  implementation("com.stripe:stripe-android:23.5.0")
  // Include the financial connections SDK to support US bank account as a payment method
  implementation("com.stripe:financial-connections:23.5.0")
}
```

> Veja mais informações sobre o último lançamento de SDK e as versões anteriores na página [Lançamentos](https://github.com/stripe/stripe-android/releases) no GitHub. Para receber notificações quando um novo lançamento for publicado, [assista aos lançamentos do repositório](https://docs.github.com/en/github/managing-subscriptions-and-notifications-on-github/configuring-notifications#configuring-your-watch-settings-for-an-individual-repository).

Configure o SDK com sua [chave publicável](https://dashboard.stripe.com/apikeys) da Stripe, de modo que seja possível fazer solicitações à API Stripe, como em sua subcategoria `Application`:

#### Kotlin

```kotlin
import com.stripe.android.PaymentConfiguration

class MyApp : Application() {
    override fun onCreate() {
        super.onCreate()
        PaymentConfiguration.init(
            applicationContext,
            "<<YOUR_PUBLISHABLE_KEY>>"
        )
    }
}
```

> Use suas [chaves de teste](https://docs.stripe.com/keys.md#obtain-api-keys) enquanto testa e desenvolve, e suas chaves de [modo de produção](https://docs.stripe.com/keys.md#test-live-modes) quando publicar seu aplicativo.

Nossas amostras de código também usam [OkHttp](https://github.com/square/okhttp) e [GSON](https://github.com/google/gson) para fazer solicitações HTTP a um servidor.

## Criar uma conta conectada
![](https://b.stripecdn.com/docs-statics-srv/assets/express-android.d13776fc7e474c2a0168a705f85b11cb.png)

> Este guia usa contas Express com determinadas [restrições](https://docs.stripe.com/connect/express-accounts.md#prerequisites-for-using-express). Você também tem a opção de avaliar [contas Custom](https://docs.stripe.com/connect/custom-accounts.md).

### Crie uma conta conectada com informações pré-preenchidas

#### Accounts v2

Use a API `/v2/core/accounts` para [criar](https://docs.stripe.com/api/v2/core/accounts/create.md) uma conta conectada, especificando o [dashboard da conta conectada e as responsabilidades](https://docs.stripe.com/connect/accounts-v2/connected-account-configuration.md).

```curl
curl -X POST https://api.stripe.com/v2/core/accounts \
  -H "Authorization: Bearer <<YOUR_SECRET_KEY>>" \
  -H "Stripe-Version: 2026-01-28.clover" \
  --json '{
    "contact_email": "furever_contact@example.com",
    "display_name": "Furever",
    "defaults": {
        "responsibilities": {
            "fees_collector": "application",
            "losses_collector": "application"
        }
    },
    "dashboard": "express",
    "identity": {
        "business_details": {
            "registered_name": "Furever"
        },
        "country": "us",
        "entity_type": "company"
    },
    "configuration": {
        "merchant": {
            "capabilities": {
                "card_payments": {
                    "requested": true
                }
            }
        },
        "recipient": {
            "capabilities": {
                "stripe_balance": {
                    "stripe_transfers": {
                        "requested": true
                    }
                }
            }
        }
    },
    "include": [
        "configuration.merchant",
        "configuration.recipient",
        "identity",
        "requirements"
    ]
  }'
```

Se você já coletou dados de suas contas conectadas, pode usá-los para preencher o objeto `Account`. Você pode preencher quaisquer dados de conta, inclusive dados pessoais e comerciais, dados de contas externas e muito mais.

Após criar uma `Conta`, crie uma [Pessoa](https://docs.stripe.com/api/v2/core/persons/create.md) para representar a pessoa responsável por abrir a conta, definindo como verdadeiro `relationship.representative` e todas as informações da conta que você queira preencher previamente (por exemplo, o nome e sobrenome).

```curl
curl -X POST https://api.stripe.com/v2/core/accounts/{{ACCOUNT_ID}}/persons \
  -H "Authorization: Bearer <<YOUR_SECRET_KEY>>" \
  -H "Stripe-Version: 2026-04-22.preview" \
  --json '{
    "given_name": "Jenny",
    "surname": "Rosen",
    "email": "jenny.rosen@example.com",
    "relationship": {
        "representative": true
    }
  }'
```

O Connect Onboarding não solicita as informações pré-preenchidas. No entanto, ele solicita que o titular da conta confirme as informações pré-preenchidas antes de aceitar o [contrato de serviços do Connect](https://docs.stripe.com/connect/service-agreement-types.md).

Ao testar sua integração, preencha antecipadamente os dados da conta usando [dados de teste](https://docs.stripe.com/connect/testing.md).

### Criar um link da conta

Você pode criar um link de conta chamando a API [Account Links v2](https://docs.stripe.com/api/v2/core/account-links.md) com os seguintes parâmetros:

- `account`
- `refresh_url`
- `return_url`
- `type` = `account_onboarding`
- `configurations` = `recipient` e `merchant`

```curl
curl -X POST https://api.stripe.com/v2/core/account_links \
  -H "Authorization: Bearer <<YOUR_SECRET_KEY>>" \
  -H "Stripe-Version: 2025-08-27.preview" \
  --json '{
    "account": "{{CONNECTEDACCOUNT_ID}}",
    "use_case": {
        "type": "account_onboarding",
        "account_onboarding": {
            "configurations": [
                "recipient",
                "merchant"
            ],
            "refresh_url": "https://example.com/reauth",
            "return_url": "https://example.com/return"
        }
    }
  }'
```

### Redirecionar o usuário ao URL do link da conta

A resposta de criação do link da conta inclui um valor de `url`. Após autenticar o usuário no seu aplicativo, redirecione-o para essa URL para inseri-lo no fluxo. As URLs de link da conta são temporárias e de uso único, pois concedem acesso às informações pessoais do usuário da conta conectada. Se desejar preencher previamente as informações, deverá preencher antes de gerar o link da conta. Depois de criar o link da conta, não será possível ler nem gravar informações na conta conectada.

> Não envie URLs de links de conta por e-mail, SMS ou outra maneira para fora do aplicativo da sua plataforma. Em vez disso, forneça-os ao titular da conta autenticado dentro do seu aplicativo.

#### Item 1

#### Swift

```swift
import UIKit
import SafariServices

let BackendAPIBaseURL: String = "" // Set to the URL of your backend server

class ConnectOnboardViewController: UIViewController {

    // ...

    override func viewDidLoad() {
        super.viewDidLoad()

        let connectWithStripeButton = UIButton(type: .system)
        connectWithStripeButton.setTitle("Connect with Stripe", for: .normal)
        connectWithStripeButton.addTarget(self, action: #selector(didSelectConnectWithStripe), for: .touchUpInside)
        view.addSubview(connectWithStripeButton)

        // ...
    }

    @objc
    func didSelectConnectWithStripe() {
        if let url = URL(string: BackendAPIBaseURL)?.appendingPathComponent("onboard-user") {
          var request = URLRequest(url: url)
          request.httpMethod = "POST"
          let task = URLSession.shared.dataTask(with: request) { (data, response, error) in
              guard let data = data,
                  let json = try? JSONSerialization.jsonObject(with: data, options: []) as? [String : Any],
                  let accountURLString = json["url"] as? String,
                  let accountURL = URL(string: accountURLString) else {
                      // handle error
              }

              let safariViewController = SFSafariViewController(url: accountURL)
              safariViewController.delegate = self

              DispatchQueue.main.async {
                  self.present(safariViewController, animated: true, completion: nil)
              }
          }
        }
    }

    // ...
}

extension ConnectOnboardViewController: SFSafariViewControllerDelegate {
    func safariViewControllerDidFinish(_ controller: SFSafariViewController) {
        // the user may have closed the SFSafariViewController instance before a redirect
        // occurred. Sync with your backend to confirm the correct state
    }
}

```

#### Item 2

```xml
<?xml version="1.0" encoding="utf-8"?>
<androidx.constraintlayout.widget.ConstraintLayout
    xmlns:android="http://schemas.android.com/apk/res/android"
    xmlns:app="http://schemas.android.com/apk/res-auto"
    xmlns:tools="http://schemas.android.com/tools"
    android:layout_width="match_parent"
    android:layout_height="match_parent"
    tools:context=".activity.ConnectWithStripeActivity">

    <Button
        android:id="@+id/connect_with_stripe"
        android:text="Connect with Stripe"
        android:layout_height="wrap_content"
        android:layout_width="wrap_content"
        app:layout_constraintBottom_toBottomOf="parent"
        app:layout_constraintEnd_toEndOf="parent"
        app:layout_constraintStart_toStartOf="parent"
        app:layout_constraintTop_toTopOf="parent"
        style="?attr/materialButtonOutlinedStyle"
        />

</androidx.constraintlayout.widget.ConstraintLayout>
```

#### Kotlin

```kotlin
class ConnectWithStripeActivity : AppCompatActivity() {

    private val viewBinding: ActivityConnectWithStripeViewBinding by lazy {
        ActivityConnectWithStripeViewBinding.inflate(layoutInflater)
    }
    private val httpClient = OkHttpClient()

    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        setContentView(viewBinding.root)

        viewBinding.connectWithStripe.setOnClickListener {
            val weakActivity = WeakReference<Activity>(this)
            val request = Request.Builder()
                .url(BACKEND_URL + "onboard-user")
                .post("".toRequestBody())
                .build()
            httpClient.newCall(request)
                .enqueue(object: Callback {
                    override fun onFailure(call: Call, e: IOException) {
                        // Request failed
                    }
                    override fun onResponse(call: Call, response: Response) {
                        if (!response.isSuccessful) {
                            // Request failed
                        } else {
                            val responseData = response.body?.string()
                            val responseJson =
                                responseData?.let { JSONObject(it) } ?: JSONObject()
                            val url = responseJson.getString("url")

                            weakActivity.get()?.let {
                                val builder: CustomTabsIntent.Builder = CustomTabsIntent.Builder()
                                val customTabsIntent = builder.build()
                                customTabsIntent.launchUrl(it, Uri.parse(url))
                            }
                        }
                    }
                })
        }
    }

    internal companion object {
        internal const val BACKEND_URL = "https://example-backend-url.com/"
    }
}
```

#### Item 3

### Gerenciar o usuário que volta à plataforma

O Connect Onboarding exige que você passe tanto um `return_url` quanto um `refresh_url` para lidar com todos os casos em que o usuário da conta é redirecionado para a sua plataforma.

> Você pode usar HTTP para seu `return_url` e para o `refresh_url` enquanto estiver em um ambiente de teste (por exemplo, para testar com o localhost), mas modo de produção aceita apenas HTTPS. Você deve atualizar URLs de teste para URLs HTTPS antes do lançamento.

#### return_url

A Stripe emite um redirecionamento para essa URL quando o usuário da conta conectada conclui o fluxo de onboarding. Isso não significa que todas as informações tenham sido recolhidas ou que não haja requisitos pendentes na conta. Significa apenas que o fluxo foi inserido e encerrado corretamente.

Nenhum estado é transmitido por essa URL. Depois que um usuário for redirecionado para o seu `return_url`, verifique o estado dos requisitos na conta dele fazendo o seguinte:

- Ouça os Webhooks `v2.core.account[requirements].updated`.
- Chame a API [Accounts v2](https://docs.stripe.com/api/v2/core/accounts/retrieve.md) e inspecione o objeto retornado.

#### refresh_url

A Stripe redireciona seu usuário para o `refresh_url` nestes casos:

- O link expirou (alguns minutos se passaram desde a criação do link).
- O usuário já acessou o URL (atualizou a página ou clicou em Voltar ou Avançar no navegador).
- Sua plataforma não consegue mais acessar a conta.
- A conta foi recusada.

Configure sua página `refresh_url` para acionar um método em seu servidor para chamar [Account Links v2](https://docs.stripe.com/api/v2/core/account-links.md) novamente com os mesmos parâmetros e redirecionar o usuário para o novo link.

### Gerenciar usuários que não concluíram o onboarding

Um usuário redirecionado para o seu `return_url` pode não ter concluído o processo de onboarding. Use o endpoint `/v2/core/accounts` para recuperar a conta do usuário e verificar se [configuration.recipient.capabilities.stripe_balance.stripe_transfers.status](https://docs.stripe.com/api/v2/core/accounts/object.md#v2_account_object-configuration-recipient-capabilities-stripe_balance-stripe_transfers-status) está coo `active`. Se o status não estiver `active` e [configuration.destinatário.capabilities.stripe_balance.stripe_transfers.status_details.code](https://docs.stripe.com/api/v2/core/accounts/object.md#v2_account_object-configuration-recipient-capabilities-stripe_balance-stripe_transfers-status_details-code) for `requirements_past_due`, forneça prompts na IU para permitir que o usuário continue o onboarding por meio de um novo link de conta. Para outros códigos, trate-os conforme necessário.

#### Accounts v1

Use a API `/v1/accounts` para [criar](https://docs.stripe.com/api/accounts/create.md) uma conta conectada especificando as [propriedades da conta conectada](https://docs.stripe.com/connect/migrate-to-controller-properties.md) ou o tipo de conta.

```curl
curl https://api.stripe.com/v1/accounts \
  -u "<<YOUR_SECRET_KEY>>:" \
  -d "controller[losses][payments]=application" \
  -d "controller[fees][payer]=application" \
  -d "controller[stripe_dashboard][type]=express"
```

Se você já coletou dados de suas contas conectadas, pode usá-los para preencher o objeto `Account`. Você pode preencher quaisquer dados de conta, inclusive dados pessoais e comerciais, dados de contas externas e muito mais.

Depois de criar uma `Account`, crie uma [Pessoa](https://docs.stripe.com/api/persons/create.md) para representar a pessoa responsável por abrir a conta, com `relationship.representative` definido como verdadeiro e informações da conta que você queira preencher previamente (por exemplo, o nome e sobrenome).

```curl
curl https://api.stripe.com/v1/accounts/{{ACCOUNT_ID}}/persons \
  -u "<<YOUR_SECRET_KEY>>:" \
  -d first_name=Jenny \
  -d last_name=Rosen \
  -d "relationship[representative]=true"
```

O Connect Onboarding não solicita as informações pré-preenchidas. No entanto, ele solicita que o titular da conta confirme as informações pré-preenchidas antes de aceitar o [contrato de serviços do Connect](https://docs.stripe.com/connect/service-agreement-types.md).

Ao testar sua integração, preencha antecipadamente os dados da conta usando [dados de teste](https://docs.stripe.com/connect/testing.md).

### Criar um link da conta

Você pode criar um link de conta chamando a API [Account Links v1](https://docs.stripe.com/api/account_links.md) com os seguintes parâmetros:

- `account`
- `refresh_url`
- `return_url`
- `type` = `account_onboarding`

```curl
curl https://api.stripe.com/v1/account_links \
  -u "<<YOUR_SECRET_KEY>>:" \
  -d "account={{CONNECTEDACCOUNT_ID}}" \
  --data-urlencode "refresh_url=https://example.com/reauth" \
  --data-urlencode "return_url=https://example.com/return" \
  -d type=account_onboarding
```

### Redirecionar o usuário ao URL do link da conta

A resposta da criação do link da conta inclui um valor de `url`. Após autenticar o usuário no seu aplicativo, redirecione-o para esta URL para inseri-lo no fluxo. As URLs de links de conta da [API Account Links v1](https://docs.stripe.com/api/account_links.md) são temporárias e de uso único, pois concedem acesso às informações pessoais do usuário da conta conectada. Autentique o usuário no seu aplicativo antes de redirecioná-lo para esta URL. Se desejar preencher previamente as informações, deverá preencher antes de gerar o link da conta. Depois de criar o link da conta, não será possível ler nem gravar informações da conta conectada.

> Não envie URLs de links de conta por e-mail, SMS ou outra maneira para fora do aplicativo da sua plataforma. Em vez disso, forneça-os ao titular da conta autenticado dentro do seu aplicativo.

#### Item 1

#### Swift

```swift
import UIKit
import SafariServices

let BackendAPIBaseURL: String = "" // Set to the URL of your backend server

class ConnectOnboardViewController: UIViewController {

    // ...

    override func viewDidLoad() {
        super.viewDidLoad()

        let connectWithStripeButton = UIButton(type: .system)
        connectWithStripeButton.setTitle("Connect with Stripe", for: .normal)
        connectWithStripeButton.addTarget(self, action: #selector(didSelectConnectWithStripe), for: .touchUpInside)
        view.addSubview(connectWithStripeButton)

        // ...
    }

    @objc
    func didSelectConnectWithStripe() {
        if let url = URL(string: BackendAPIBaseURL)?.appendingPathComponent("onboard-user") {
          var request = URLRequest(url: url)
          request.httpMethod = "POST"
          let task = URLSession.shared.dataTask(with: request) { (data, response, error) in
              guard let data = data,
                  let json = try? JSONSerialization.jsonObject(with: data, options: []) as? [String : Any],
                  let accountURLString = json["url"] as? String,
                  let accountURL = URL(string: accountURLString) else {
                      // handle error
              }

              let safariViewController = SFSafariViewController(url: accountURL)
              safariViewController.delegate = self

              DispatchQueue.main.async {
                  self.present(safariViewController, animated: true, completion: nil)
              }
          }
        }
    }

    // ...
}

extension ConnectOnboardViewController: SFSafariViewControllerDelegate {
    func safariViewControllerDidFinish(_ controller: SFSafariViewController) {
        // the user may have closed the SFSafariViewController instance before a redirect
        // occurred. Sync with your backend to confirm the correct state
    }
}

```

#### Item 2

```xml
<?xml version="1.0" encoding="utf-8"?>
<androidx.constraintlayout.widget.ConstraintLayout
    xmlns:android="http://schemas.android.com/apk/res/android"
    xmlns:app="http://schemas.android.com/apk/res-auto"
    xmlns:tools="http://schemas.android.com/tools"
    android:layout_width="match_parent"
    android:layout_height="match_parent"
    tools:context=".activity.ConnectWithStripeActivity">

    <Button
        android:id="@+id/connect_with_stripe"
        android:text="Connect with Stripe"
        android:layout_height="wrap_content"
        android:layout_width="wrap_content"
        app:layout_constraintBottom_toBottomOf="parent"
        app:layout_constraintEnd_toEndOf="parent"
        app:layout_constraintStart_toStartOf="parent"
        app:layout_constraintTop_toTopOf="parent"
        style="?attr/materialButtonOutlinedStyle"
        />

</androidx.constraintlayout.widget.ConstraintLayout>
```

#### Kotlin

```kotlin
class ConnectWithStripeActivity : AppCompatActivity() {

    private val viewBinding: ActivityConnectWithStripeViewBinding by lazy {
        ActivityConnectWithStripeViewBinding.inflate(layoutInflater)
    }
    private val httpClient = OkHttpClient()

    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        setContentView(viewBinding.root)

        viewBinding.connectWithStripe.setOnClickListener {
            val weakActivity = WeakReference<Activity>(this)
            val request = Request.Builder()
                .url(BACKEND_URL + "onboard-user")
                .post("".toRequestBody())
                .build()
            httpClient.newCall(request)
                .enqueue(object: Callback {
                    override fun onFailure(call: Call, e: IOException) {
                        // Request failed
                    }
                    override fun onResponse(call: Call, response: Response) {
                        if (!response.isSuccessful) {
                            // Request failed
                        } else {
                            val responseData = response.body?.string()
                            val responseJson =
                                responseData?.let { JSONObject(it) } ?: JSONObject()
                            val url = responseJson.getString("url")

                            weakActivity.get()?.let {
                                val builder: CustomTabsIntent.Builder = CustomTabsIntent.Builder()
                                val customTabsIntent = builder.build()
                                customTabsIntent.launchUrl(it, Uri.parse(url))
                            }
                        }
                    }
                })
        }
    }

    internal companion object {
        internal const val BACKEND_URL = "https://example-backend-url.com/"
    }
}
```

### Gerenciar o usuário que volta à plataforma

O Connect Onboarding exige que você passe um `return_url` e `refresh_url` para gerenciar todos os casos em que o usuário é redirecionado à sua plataforma. É importante implementá-los corretamente para proporcionar a melhor experiência ao usuário.

> Você pode usar HTTP para seu `return_url` e para o `refresh_url` enquanto estiver em um ambiente de teste (por exemplo, para testar com o localhost), mas modo de produção aceita apenas HTTPS. Você deve atualizar URLs de teste para URLs HTTPS antes do lançamento.

#### return_url

A Stripe emite um redirecionamento para essa URL quando o usuário da conta conectada conclui o fluxo de onboarding. Isso não significa que todas as informações tenham sido recolhidas ou que não haja requisitos pendentes na conta. Significa apenas que o fluxo foi inserido e encerrado corretamente.

Nenhum estado é passado por este URL. Após o redirecionamento de um usuário para o `return_url` , verifique o estado do parâmetro `details_submitted` na conta dele realizando uma das seguintes ações:

- Ouça os Webhooks `account.updated`
- Chame a API [Accounts v1](https://docs.stripe.com/api/accounts.md) e inspecione o objeto retornado

#### refresh_url

A Stripe redireciona seu usuário para o `refresh_url` nestes casos:

- O link expirou (alguns minutos se passaram desde a criação do link).
- O usuário já acessou o URL (atualizou a página ou clicou em Voltar ou Avançar no navegador).
- Sua plataforma não consegue mais acessar a conta.
- A conta foi recusada.

Configure sua página `refresh_url` para acionar um método em seu servidor para chamar [Account Links v1](https://docs.stripe.com/api/account_links.md) novamente com os mesmos parâmetros e redirecionar o usuário para o novo link.

### Gerenciar usuários que não concluíram o onboarding

Um usuário que é redirecionado para seu `return_url` pode não ter concluído o processo de onboarding. Use o endpoint `/v1/accounts` para recuperar a conta do usuário e verificar se `charges_enabled`. Se a conta não estiver totalmente integrada, forneça prompts de IU para permitir que o usuário continue fazendo onboarding por meio de um novo link de conta. Você pode determinar se eles concluíram o onboarding verificando o estado do parâmetro `details_submitted` na conta deles.

## Habilitar formas de pagamento

Veja as [configurações de formas de pagamento](https://dashboard.stripe.com/settings/connect/payment_methods) e ative as que pretende aceitar. Pagamentos com cartão, Google Pay e Apple Pay são ativados por padrão, mas você pode ativar e desativar as formas de pagamento conforme a necessidade.

Antes da exibição das formas de pagamento, a Stripe avalia a moeda, as restrições e outros parâmetros dessas formas de pagamento para criar a lista das que são aceitas. Priorizamos as que aumentam a conversão e são mais relevantes para a moeda e a localização do cliente. As formas de pagamento de menor prioridade são ocultas em um menu de estouro.

## Adicionar um endpoint [Lado do servidor]

> #### Nota
> 
> Para exibir o PaymentSheet antes de criar um PaymentIntent, consulte [Colete os dados de pagamento antes de criar um Intent](https://docs.stripe.com/payments/accept-a-payment-deferred.md?type=payment).

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

1. [PaymentIntent](https://docs.stripe.com/api/payment_intents.md): 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.

1. (Opcional) Uma [conta configurada pelo cliente](https://docs.stripe.com/api/v2/core/accounts/object.md#v2_account_object-applied_configurations) ou um objeto [Cliente](https://docs.stripe.com/api/customers.md): para configurar uma forma de pagamento para pagamentos futuros, você deve associá-la a um cliente. Crie um objeto para representar seu cliente quando ele criar uma conta na sua empresa. Se o cliente fizer um pagamento como convidado, você poderá criar um objeto `Conta` ou `Cliente` antes do pagamento e associá-lo à sua própria representação interna da conta do cliente posteriormente.

1. (Opcional) [CustomerSession](https://docs.stripe.com/api/customer_sessions.md): os dados do objeto que representa seu cliente são confidenciais e não podem ser recuperados diretamente de um aplicativo. Uma `CustomerSession` concede ao SDK acesso temporário e restrito à `Conta` ou ao `Cliente` e oferece opções de configuração adicionais. Consulte a lista completa de [opções de configuração](https://docs.stripe.com/api/customer_sessions/create.md#create_customer_session-components).

> Se você nunca salvar cartões para os clientes e não permitir que clientes recorrentes reutilizem cartões salvos, poderá omitir os objetos `Conta` ou `Cliente` e o objeto `CustomerSession` da sua integração.

Por motivos de segurança, o aplicativo não pode criar esses objetos. Para isso, adicione um endpoint ao servidor para:

1. Recupera a `Conta` ou o `Cliente` ou cria um novo.
1. Cria uma [CustomerSession](https://docs.stripe.com/api/customer_sessions.md) para a `Conta` ou o `Cliente`.
1. Cria um `PaymentIntent` com o [valor](https://docs.stripe.com/api/payment_intents/create.md#create_payment_intent-amount), a [moeda](https://docs.stripe.com/api/payment_intents/create.md#create_payment_intent-currency), e a [customer_account](https://docs.stripe.com/api/payment_intents/create.md#create_payment_intent-customer_account) ou o [cliente](https://docs.stripe.com/api/payment_intents/create.md#create_payment_intent-customer).
1. Retorna o *segredo do cliente* (The client secret is a unique key returned from Stripe as part of a PaymentIntent. This key lets the client access important fields from the PaymentIntent (status, amount, currency) while hiding sensitive ones (metadata, customer)) do `PaymentIntent`, o `client_secret` da `CustomerSession`, o ID da `Conta` ou do `Cliente` e sua [chave de publicação](https://dashboard.stripe.com/apikeys) do seu 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.

#### Gerenciar formas de pagamento no Dashboard

Você pode gerenciar formas de pagamento no [Dashboard](https://dashboard.stripe.com/settings/payment_methods). A Stripe processa a devolução de formas de pagamento qualificadas com base em fatores como valor, moeda e fluxo de pagamento da transação. O PaymentIntent é criado usando as formas de pagamento configuradas no Dashboard. Se não quiser usar o Dashboard ou se quiser especificar formas de pagamento manualmente, você pode listá-las usando o atributo `payment_method_types`.

#### curl

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

# Create an CustomerSession for the Customer
curl https://api.stripe.com/v1/customer_sessions \
  -u <<YOUR_SECRET_KEY>>: \
  -X "POST" \
  -d "customer"="{{CUSTOMER_ID}}" \
  -d "components[mobile_payment_element][enabled]"=true \
  -d "components[mobile_payment_element][features][payment_method_save]"=enabled \
  -d "components[mobile_payment_element][features][payment_method_redisplay]"=enabled \
  -d "components[mobile_payment_element][features][payment_method_remove]"=enabled

# Create a PaymentIntent
curl https://api.stripe.com/v1/payment_intents \
  -u <<YOUR_SECRET_KEY>>: \
  -X "POST" \
  -d "customer"="{{CUSTOMER_ID}}" \
  -d "amount"=1099 \
  -d "currency"="eur" \

  -d "automatic_payment_methods[enabled]"=true \
  -d application_fee_amount="123" \
  -d "transfer_data[destination]"="{{CONNECTED_ACCOUNT_ID}}" \
```

#### Listar manualmente as formas de pagamento

#### curl

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

# Create an CustomerSession for the Customer
curl https://api.stripe.com/v1/customer_sessions \
  -u <<YOUR_SECRET_KEY>>: \
  -X "POST" \
  -d "customer"="{{CUSTOMER_ID}}" \
  -d "components[mobile_payment_element][enabled]"=true \
  -d "components[mobile_payment_element][features][payment_method_save]"=enabled \
  -d "components[mobile_payment_element][features][payment_method_redisplay]"=enabled \
  -d "components[mobile_payment_element][features][payment_method_remove]"=enabled

# Create a PaymentIntent
curl https://api.stripe.com/v1/payment_intents \
  -u <<YOUR_SECRET_KEY>>: \
  -X "POST" \
  -d "customer"="{{CUSTOMER_ID}}" \
  -d "amount"=1099 \
  -d "currency"="eur" \
  -d "payment_method_types[]"="bancontact" \
  -d "payment_method_types[]"="card" \
  -d "payment_method_types[]"="ideal" \
  -d "payment_method_types[]"="klarna" \
  -d "payment_method_types[]"="sepa_debit" \
  -d application_fee_amount="123" \
  -d "transfer_data[destination]"="{{CONNECTED_ACCOUNT_ID}}" \
```

> A forma de pagamento precisa aceitar a moeda passada no PaymentIntent. Além disso, sua empresa precisa estar estabelecida em um dos países aceitos pela forma de pagamento. Consulte a página [Opções de integração de formas de pagamento](https://docs.stripe.com/payments/payment-methods/integration-options.md) para obter mais detalhes sobre o que é aceito.

## Integrar a descrição da compra [Lado do cliente]

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
- Colete todas as informações de envio necessárias usando o [Address Element](https://docs.stripe.com/elements/address-element.md?platform=android)
- Incluir um botão de checkout para apresentar a IU da Stripe

#### Jetpack Compose

[Inicializar](https://stripe.dev/stripe-android/paymentsheet/com.stripe.android.paymentsheet/-payment-sheet/-builder/index.html) uma instância de `PaymentSheet` dentro de `onCreate` da sua atividade de checkout, passando um método para gerenciar o resultado.

```kotlin
import androidx.compose.runtime.Composable
import androidx.compose.runtime.remember
import com.stripe.android.paymentsheet.PaymentSheet
import com.stripe.android.paymentsheet.PaymentSheetResult

@Composable
fun App() {
  val paymentSheet = remember { PaymentSheet.Builder(::onPaymentSheetResult) }.build()
}

private fun onPaymentSheetResult(paymentSheetResult: PaymentSheetResult) {
  // implemented in the next steps
}
```

Em seguida, busque o segredo do cliente de Intenção Payment, o segredo do cliente da Sessão do cliente, a ID do cliente e a chave publicável do endpoint que você criou na etapa anterior. Defina a chave publicável usando`PaymentConfiguration` e armazene os outros para uso quando apresentar o PaymentSheet.

```kotlin
import androidx.compose.runtime.Composable
import androidx.compose.runtime.rememberimport androidx.compose.runtime.LaunchedEffect
import androidx.compose.runtime.getValue
import androidx.compose.runtime.mutableStateOf
import androidx.compose.runtime.setValue
import androidx.compose.ui.platform.LocalContext
import com.stripe.android.PaymentConfiguration
import com.stripe.android.paymentsheet.PaymentSheet
import com.stripe.android.paymentsheet.PaymentSheetResult

@Composable
fun App() {
  val paymentSheet = remember { PaymentSheet.Builder(::onPaymentSheetResult) }.build()val context = LocalContext.current
  var customerConfig by remember { mutableStateOf<PaymentSheet.CustomerConfiguration?>(null) }
  varpaymentIntentClientSecret by remember { mutableStateOf<String?>(null) }

  LaunchedEffect(context) {
    // Make a request to your own server and retrieve payment configurations
    val networkResult = ...
    if (networkResult.isSuccess) {paymentIntentClientSecret = networkResult.paymentIntent
        customerConfig = PaymentSheet.CustomerConfiguration.createWithCustomerSession(
          id = networkResult.customer,
          clientSecret = networkResult.customerSessionClientSecret
        )PaymentConfiguration.init(context, networkResult.publishableKey)}
  }
}

private fun onPaymentSheetResult(paymentSheetResult: PaymentSheetResult) {
  // implemented in the next steps
}
```

Quando o cliente tocar no botão checkout, chame [presentWithPaymentIntent](https://stripe.dev/stripe-android/paymentsheet/com.stripe.android.paymentsheet/-payment-sheet/index.html#1814490530%2FFunctions%2F2002900378) para apresentar a descrição da compra. Depois que o cliente conclui o pagamento, a descrição é descartada e o [PaymentSheetResultCallback](https://stripe.dev/stripe-android/paymentsheet/com.stripe.android.paymentsheet/-payment-sheet-result-callback/index.html) é chamado com um [PaymentSheetResult](https://stripe.dev/stripe-android/paymentsheet/com.stripe.android.paymentsheet/-payment-sheet-result/index.html).

```kotlin
import androidx.compose.material.Button
import androidx.compose.material.Text
import androidx.compose.runtime.Composable
import androidx.compose.runtime.LaunchedEffect
import androidx.compose.runtime.getValue
import androidx.compose.runtime.mutableStateOf
import androidx.compose.runtime.remember
import androidx.compose.runtime.setValue
import androidx.compose.ui.platform.LocalContext
import com.stripe.android.PaymentConfiguration
import com.stripe.android.paymentsheet.PaymentSheet
import com.stripe.android.paymentsheet.PaymentSheetResult

@Composable
fun App() {
  val paymentSheet = remember { PaymentSheet.Builder(::onPaymentSheetResult) }.build()
  val context = LocalContext.current
  var customerConfig by remember { mutableStateOf<PaymentSheet.CustomerConfiguration?>(null) }
  var paymentIntentClientSecret by remember { mutableStateOf<String?>(null) }

  LaunchedEffect(context) {
    // Make a request to your own server and retrieve payment configurations
    val networkResult = ...
    if (networkResult.isSuccess) {
        paymentIntentClientSecret = networkResult.paymentIntent
        customerConfig = PaymentSheet.CustomerConfiguration.createWithCustomerSession(
          id = networkResult.customer,
          clientSecret = networkResult.customerSessionClientSecret
        )
        PaymentConfiguration.init(context, networkResult.publishableKey)
    }
  }Button(
    onClick = {
      val currentConfig = customerConfig
      val currentClientSecret =paymentIntentClientSecret

      if (currentConfig != null && currentClientSecret != null) {
        presentPaymentSheet(paymentSheet, currentConfig, currentClientSecret)
      }
    }
  ) {
    Text("Checkout")
  }
}private fun presentPaymentSheet(
  paymentSheet: PaymentSheet,
  customerConfig: PaymentSheet.CustomerConfiguration,paymentIntentClientSecret: String
) {
  paymentSheet.presentWithPaymentIntent(paymentIntentClientSecret,
    PaymentSheet.Configuration.Builder(merchantDisplayName = "My merchant name")
      .customer(customerConfig)
      // Set `allowsDelayedPaymentMethods` to true if your business handles
      // delayed notification payment methods like US bank accounts.
      .allowsDelayedPaymentMethods(true)
      .build()
  )
}
private fun onPaymentSheetResult(paymentSheetResult: PaymentSheetResult) {when(paymentSheetResult) {
    is PaymentSheetResult.Canceled -> {
      print("Canceled")
    }
    is PaymentSheetResult.Failed -> {
      print("Error: ${paymentSheetResult.error}")
    }
    is PaymentSheetResult.Completed -> {
      // Display for example, an order confirmation screen
      print("Completed")
    }
  }
}
```

#### Visualizações (Clássico)

[Inicialize](https://stripe.dev/stripe-android/paymentsheet/com.stripe.android.paymentsheet/-payment-sheet/index.html#-394860221%2FConstructors%2F2002900378) uma instância de `PaymentSheet` dentro de `onCreate` da sua atividade de checkout, passando um método para gerenciar o resultado.

#### Kotlin

```kotlin
import com.stripe.android.paymentsheet.PaymentSheet

class CheckoutActivity : AppCompatActivity() {
  lateinit var paymentSheet: PaymentSheet

  override fun onCreate(savedInstanceState: Bundle?) {
    super.onCreate(savedInstanceState)
    paymentSheet = PaymentSheet.Builder(::onPaymentSheetResult).build(this)
  }

  fun onPaymentSheetResult(paymentSheetResult: PaymentSheetResult) {
    // implemented in the next steps
  }
}
```

Em seguida, busque o segredo do cliente de Intenção Payment, o segredo do cliente da Sessão do cliente, a ID do cliente e a chave publicável do endpoint que você criou na etapa anterior. Defina a chave publicável usando`PaymentConfiguration` e armazene os outros para uso quando apresentar o PaymentSheet.

#### Kotlin

```kotlin
import com.stripe.android.paymentsheet.PaymentSheet

class CheckoutActivity : AppCompatActivity() {
  lateinit var paymentSheet: PaymentSheetlateinit var customerConfig: PaymentSheet.CustomerConfiguration
  lateinit varpaymentIntentClientSecret: String

  override fun onCreate(savedInstanceState: Bundle?) {
    super.onCreate(savedInstanceState)
    paymentSheet = PaymentSheet.Builder(::onPaymentSheetResult).build(this)lifecycleScope.launch {
      // Make a request to your own server and retrieve payment configurations
      val networkResult = MyBackend.getPaymentConfig()
      if (networkResult.isSuccess) {paymentIntentClientSecret = networkResult.paymentIntent
        customerConfig = PaymentSheet.CustomerConfiguration.createWithCustomerSession(
          id = networkResult.customer,
          clientSecret = networkResult.customerSessionClientSecret
        )PaymentConfiguration.init(context, networkResult.publishableKey)}
    }
  }

  fun onPaymentSheetResult(paymentSheetResult: PaymentSheetResult) {
    // implemented in the next steps
  }
}
```

Quando o cliente tocar no botão checkout, chame [presentWithPaymentIntent](https://stripe.dev/stripe-android/paymentsheet/com.stripe.android.paymentsheet/-payment-sheet/index.html#1814490530%2FFunctions%2F2002900378) para apresentar a descrição da compra. Depois que o cliente conclui o pagamento, a descrição é descartada e o [PaymentSheetResultCallback](https://stripe.dev/stripe-android/paymentsheet/com.stripe.android.paymentsheet/-payment-sheet-result-callback/index.html) é chamado com um [PaymentSheetResult](https://stripe.dev/stripe-android/paymentsheet/com.stripe.android.paymentsheet/-payment-sheet-result/index.html).

#### Kotlin

```kotlin
// ...
class CheckoutActivity : AppCompatActivity() {
  lateinit var paymentSheet: PaymentSheet
  lateinit var customerConfig: PaymentSheet.CustomerConfiguration
  lateinit var paymentIntentClientSecret: String
  // ...fun presentPaymentSheet() {
    paymentSheet.presentWithPaymentIntent(paymentIntentClientSecret,
      PaymentSheet.Configuration.Builder(merchantDisplayName = "My merchant name")
        .customer(customerConfig)
        // Set `allowsDelayedPaymentMethods` to true if your business handles
        // delayed notification payment methods like US bank accounts.
        .allowsDelayedPaymentMethods(true)
        .build()
    )
  }

  fun onPaymentSheetResult(paymentSheetResult: PaymentSheetResult) {when(paymentSheetResult) {
      is PaymentSheetResult.Canceled -> {
        print("Canceled")
      }
      is PaymentSheetResult.Failed -> {
        print("Error: ${paymentSheetResult.error}")
      }
      is PaymentSheetResult.Completed -> {
        // Display for example, an order confirmation screen
        print("Completed")
      }
    }
  }
}
```

Configurar `allowsDelayedPaymentMethods` como verdadeiro permite formas de pagamento de [notificação assíncrona](https://docs.stripe.com/payments/payment-methods.md#payment-notification) 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.

## Gerenciar eventos pós-pagamento [Lado do servidor]

Stripe envia um evento [payment_intent.succeeded](https://docs.stripe.com/api/events/types.md#event_types-payment_intent.succeeded) quando o pagamento é concluído. Use a [ferramenta Dashboard webhook](https://dashboard.stripe.com/webhooks) ou siga o [guia de webhooks](https://docs.stripe.com/webhooks/quickstart.md) 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](https://stripe.com/payments/payment-methods-guide) 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:

| Evento                                                                                                                          | Descrição                                                                                                                                                                                                                                                                     | Ação                                                                                                                                                                                            |
| ------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [payment_intent.succeeded](https://docs.stripe.com/api/events/types.md?lang=php#event_types-payment_intent.succeeded)           | Enviado quando um cliente conclui um pagamento com êxito.                                                                                                                                                                                                                     | Envie ao cliente uma confirmação de pedido e *processe* (Fulfillment is the process of providing the goods or services purchased by a customer, typically after payment is collected) o pedido. |
| [payment_intent.processing](https://docs.stripe.com/api/events/types.md?lang=php#event_types-payment_intent.processing)         | Enviado quando um cliente inicia um pagamento, mas o pagamento ainda precisa ser concluído. Esse evento costuma ser enviado quando um cliente inicia um débito bancário. Ele é seguido por um evento `payment_intent.succeeded` ou `payment_intent.payment_failed` no futuro. | Envie ao cliente uma confirmação do pedido que indica que o pagamento está pendente. Para produtos digitais, pode ser necessário executar o pedido antes de aguardar a conclusão do pagamento.  |
| [payment_intent.payment_failed](https://docs.stripe.com/api/events/types.md?lang=php#event_types-payment_intent.payment_failed) | Enviado quando um cliente tenta fazer um pagamento, mas o pagamento falha.                                                                                                                                                                                                    | Se um pagamento passa de `processing` para `payment_failed`, ofereça ao cliente outra tentativa para pagar.                                                                                     |

## Testar a integração

#### Cartões

| Número do cartão    | Cenário                                                                                                                                                                                                                                                                                             | Como testar                                                                                                                 |
| ------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------- |
| 4242424242424242    | O pagamento com cartão é bem-sucedido e não precisa de autenticação.                                                                                                                                                                                                                                | Preencha o formulário do cartão de crédito usando o número do cartão de crédito com qualquer validade, CVC e código postal. |
| 4000002500003155    | O pagamento com cartão precisa de *autenticação* (Strong Customer Authentication (SCA) is a regulatory requirement in effect as of September 14, 2019, that impacts many European online payments. It requires customers to use two-factor authentication like 3D Secure to verify their purchase). | Preencha o formulário do cartão de crédito usando o número do cartão de crédito com qualquer validade, CVC e código postal. |
| 4000000000009995    | O cartão é recusado com um código de recusa como `insufficient_funds`.                                                                                                                                                                                                                              | Preencha o formulário do cartão de crédito usando o número do cartão de crédito com qualquer validade, CVC e código postal. |
| 6205500000000000004 | O cartão UnionPay tem um comprimento variável de 13 a 19 dígitos.                                                                                                                                                                                                                                   | Preencha o formulário do cartão de crédito usando o número do cartão de crédito com qualquer validade, CVC e código postal. |

#### Débito bancário autenticado

| Forma de pagamento | Cenário                                                                                                                                                                                                | Como testar                                                                                                                                                                                                |
| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Bancontact, iDEAL  | Seu cliente não faz a autenticação na página de redirecionamento de uma forma de pagamento baseada em redirecionamento e notificação imediata.                                                         | Escolha qualquer forma de pagamento baseada em redirecionamento, preencha os dados obrigatórios e confirme o pagamento. Em seguida, clique em **Falhar pagamento de teste** na página de redirecionamento. |
| Pay by Bank        | O cliente paga com uma forma de pagamento baseada em redirecionamento e [notificação posterior](https://docs.stripe.com/payments/payment-methods.md#payment-notification).                             | Escolha a forma de pagamento, preencha os dados obrigatórios e confirme o pagamento. Em seguida, clique em **Concluir o pagamento de teste** na página de redirecionamento.                                |
| Pay by Bank        | Seu cliente não faz a autenticação na página de redirecionamento de uma forma de pagamento baseada em redirecionamento e notificação posterior.                                                        | Escolha a forma de pagamento, preencha os dados obrigatórios e confirme o pagamento. Em seguida, clique em **Falhar o pagamento de teste** na página de redirecionamento.                                  |
| BLIK               | Os pagamentos BLIK falham de várias formas: falhas imediatas (por exemplo, o código está vencido ou inválido), erros atrasados (o banco recusa) ou limites de tempo (o cliente não respondeu a tempo). | Use padrões de e-mail para [simular as diferentes falhas.](https://docs.stripe.com/payments/blik/accept-a-payment.md#simulate-failures)                                                                    |

#### Débitos bancários

| Forma de pagamento     | Cenário                                                                                           | Como testar                                                                                                                                                                     |
| ---------------------- | ------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Débito automático SEPA | O cliente paga com débito automático SEPA.                                                        | Preencha o formulário usando o número de conta `AT321904300235473204`. Inicialmente, o status do PaymentIntent muda para processando e, três minutos depois, para bem-sucedido. |
| Débito automático SEPA | O status da intenção de pagamento do cliente muda de `processing` para `requires_payment_method`. | Preencha o formulário usando o número de conta `AT861904300235473202`.                                                                                                          |

Consulte [Testes](https://docs.stripe.com/testing.md) para obter mais informações sobre como testar sua integração.

## Optional: Habilitar Google Pay

### Configurar a integração

Para usar o Google Pay, habilite a API Google Pay adicionando o seguinte à `<application>` tag do seu **AndroidManifest.xml**:

```xml
<application>
  ...
  <meta-data
    android:name="com.google.android.gms.wallet.api.enabled"
    android:value="true" />
</application>
```

Veja mais detalhes na [Configuração da API Google Pay](https://developers.google.com/pay/api/android/guides/setup) do Google Pay para Android.

### Adicionar Google Pay

Para adicionar o Google Pay à sua integração, passe uma [PaymentSheet.GooglePayConfiguration](https://stripe.dev/stripe-android/paymentsheet/com.stripe.android.paymentsheet/-payment-sheet/-google-pay-configuration/index.html) com seu ambiente do Google Pay (produção ou teste) e o [código do país da sua empresa](https://dashboard.stripe.com/settings/account) quando inicializar [PaymentSheet.Configuration](https://stripe.dev/stripe-android/paymentsheet/com.stripe.android.paymentsheet/-payment-sheet/-configuration/index.html).

#### Kotlin

```kotlin
val googlePayConfiguration = PaymentSheet.GooglePayConfiguration(
  environment = PaymentSheet.GooglePayConfiguration.Environment.Test,
  countryCode = "US",
  currencyCode = "USD" // Required for Setup Intents, optional for Payment Intents
)
val configuration = PaymentSheet.Configuration.Builder(merchantDisplayName = "My merchant name")
  .googlePay(googlePayConfiguration)
  .build()
```

### Testar Google Pay

O Google permite que você faça pagamentos de teste por meio de seu [Pacote de cartão de teste](https://developers.google.com/pay/api/android/guides/resources/test-card-suite). O Pacote de cartão de teste é compatível com os [cartões de teste](https://docs.stripe.com/testing.md) da Stripe.

Você precisa testar o Google Pay usando um dispositivo Android físico em vez de um dispositivo simulado, em um país onde o Google Pay é compatível. Faça login em uma conta do Google em seu dispositivo de teste com um cartão real salvo na Carteira do Google.

## Optional: Personalizar a descrição

Toda personalização é configurada usando o objeto [PaymentSheet.Configuration](https://stripe.dev/stripe-android/paymentsheet/com.stripe.android.paymentsheet/-payment-sheet/-configuration/index.html).

### Aparência

Personalize cores, fontes e assim por diante para combinar com a aparência do seu aplicativo usando a [API appearance](https://docs.stripe.com/elements/appearance-api/mobile.md?platform=android).

### Layout da forma de pagamento

Configure o layout das formas de pagamento na planilha usando [paymentMethodLayout](https://stripe.dev/stripe-android/paymentsheet/com.stripe.android.paymentsheet/-payment-sheet/-configuration/-builder/index.html#2123253356%2FFunctions%2F2002900378). Você pode exibi-los horizontalmente, verticalmente ou deixar a Stripe otimizar o layout automaticamente.
![](https://b.stripecdn.com/docs-statics-srv/assets/android-mpe-payment-method-layouts.3bcfe828ceaad1a94e0572a22d91733f.png)

#### Kotlin

```kotlin
PaymentSheet.Configuration.Builder("Example, Inc.")
  .paymentMethodLayout(PaymentSheet.PaymentMethodLayout.Automatic)
  .build()
```

### Coletar endereços de usuários

Colete endereços de entrega ou cobrança locais e internacionais de seus clientes usando o [Address Element](https://docs.stripe.com/elements/address-element.md?platform=android).

### Nome de exibição da empresa

Especifique o nome da empresa exibido para o cliente definindo [merchantDisplayName](https://stripe.dev/stripe-android/paymentsheet/com.stripe.android.paymentsheet/-payment-sheet/-configuration/index.html#-191101533%2FProperties%2F2002900378). Por padrão, esse é o nome do seu aplicativo.

#### Kotlin

```kotlin
PaymentSheet.Configuration.Builder(
  merchantDisplayName = "My app, Inc."
).build()
```

### Modo escuro

Por padrão, o `PaymentSheet` se adapta automaticamente às configurações de aparência do sistema do usuário (modo claro e escuro). É possível alterar isso configurando modo claro ou escuro no seu aplicativo:

#### Kotlin

```kotlin
// force dark
AppCompatDelegate.setDefaultNightMode(AppCompatDelegate.MODE_NIGHT_YES)
// force light
AppCompatDelegate.setDefaultNightMode(AppCompatDelegate.MODE_NIGHT_NO)
```

### Dados de faturamento padrão

Para definir valores padrão para dados de faturamento coletados na descrição da compra, configure a propriedade `defaultBillingDetails`. A `PaymentSheet` preenche previamente seus campos com os valores que você informou.

#### Kotlin

```kotlin
val address = PaymentSheet.Address(country = "US")
val billingDetails = PaymentSheet.BillingDetails(
  address = address,
  email = "foo@bar.com"
)
val configuration = PaymentSheet.Configuration.Builder(merchantDisplayName = "Merchant, Inc.")
  .defaultBillingDetails(billingDetails)
  .build()
```

### Configurar coleta de dados de cobrança

Usar `BillingDetailsCollectionConfiguration` para especificar como você deseja coletar dados de cobrança no PaymentSheet.

Você pode coletar o nome, e-mail, número de telefone e endereço do cliente.

Se quiser anexar detalhes de cobrança padrão ao objeto PaymentMethod mesmo quando esses campos não forem coletados na IU, defina `billingDetailsCollectionConfiguration.attachDefaultsToPaymentMethod` como `true`.

#### Kotlin

```kotlin
val billingDetails = PaymentSheet.BillingDetails(
  email = "foo@bar.com"
)
val billingDetailsCollectionConfiguration = BillingDetailsCollectionConfiguration(
  attachDefaultsToPaymentMethod = true,
  name = BillingDetailsCollectionConfiguration.CollectionMode.Always,
  email = BillingDetailsCollectionConfiguration.CollectionMode.Never,
  address = BillingDetailsCollectionConfiguration.AddressCollectionMode.Full,
)
val configuration = PaymentSheet.Configuration.Builder(merchantDisplayName = "Merchant, Inc.")
  .defaultBillingDetails(billingDetails)
  .billingDetailsCollectionConfiguration(billingDetailsCollectionConfiguration)
  .build()
```

> Consulte seu jurídico sobre as leis que se aplicam à coleta de dados. Só colete números de telefone se precisar deles para a transação.

## Optional: Conclua o pagamento em sua IU

Você pode exibir a Payment Sheet apenas para coletar dados da forma de pagamento e concluir o pagamento na IU do aplicativo. Isso é útil quando você tem um botão de compra personalizado ou precisa de mais etapas após a coleta dos dados do pagamento.
![](https://b.stripecdn.com/docs-statics-srv/assets/android-multi-step.84d8a0a44b1baa596bda491322b6d9fd.png)

> Um exemplo de integração está [disponível no nosso GitHub](https://github.com/stripe/stripe-android/blob/master/paymentsheet-example/src/main/java/com/stripe/android/paymentsheet/example/samples/ui/paymentsheet/custom_flow/CustomFlowActivity.kt).

1. Primeiro, inicialize [PaymentSheet.FlowController](https://stripe.dev/stripe-android/paymentsheet/com.stripe.android.paymentsheet/-payment-sheet/-flow-controller/index.html) em vez de `PaymentSheet` usando um dos métodos do [Builder](https://stripe.dev/stripe-android/paymentsheet/com.stripe.android.paymentsheet/-payment-sheet/-flow-controller/-builder/index.html).

#### Android (Kotlin)

```kotlin
class CheckoutActivity : AppCompatActivity() {
  private lateinit var flowController: PaymentSheet.FlowController

  override fun onCreate(savedInstanceState: Bundle?) {
    super.onCreate(savedInstanceState)

    val flowController = PaymentSheet.FlowController.Builder(
      resultCallback = ::onPaymentSheetResult,
      paymentOptionResultCallback = ::onPaymentOption,
    ).build(this)
  }
}
```

1. Em seguida, chame `configureWithPaymentIntent` com as chaves do objeto Stripe recuperadas do backend e atualize a IU no callback usando [getPaymentOption()](https://stripe.dev/stripe-android/paymentsheet/com.stripe.android.paymentsheet/-payment-sheet/-flow-controller/index.html#-2091462043%2FFunctions%2F2002900378). Isso contém uma imagem e um rótulo que representam a forma de pagamento selecionada atualmente pelo cliente.

#### Android (Kotlin)

```kotlin
flowController.configureWithPaymentIntent(
  paymentIntentClientSecret = paymentIntentClientSecret,
  configuration = PaymentSheet.Configuration.Builder("Example, Inc.")
    .customer(PaymentSheet.CustomerConfiguration(
      id = customerId,
      ephemeralKeySecret = ephemeralKeySecret
    ))
    .build()
) { isReady, error ->
  if (isReady) {
    // Update your UI using `flowController.getPaymentOption()`
  } else {
    // handle FlowController configuration failure
  }
}
```

1. Em seguida, chame [presentPaymentOptions](https://stripe.dev/stripe-android/paymentsheet/com.stripe.android.paymentsheet/-payment-sheet/-flow-controller/index.html#449924733%2FFunctions%2F2002900378) para coletar os detalhes do pagamento. Quando o cliente termina, a descrição da compra é descartada e chama o [paymentOptionCallback](https://stripe.dev/stripe-android/paymentsheet/com.stripe.android.paymentsheet/-payment-option-callback/index.html) passado anteriormente em `create`. Implemente essa forma para atualizar a IU com o `paymentOption` retornado.

#### Android (Kotlin)

```kotlin
// ...
  flowController.presentPaymentOptions()
// ...
  private fun onPaymentOption(paymentOptionResult: PaymentOptionResult) {
    val paymentOption = paymentOptionResult.paymentOption
    if (paymentOption != null) {
      paymentMethodButton.text = paymentOption.label
      paymentMethodButton.setCompoundDrawablesRelativeWithIntrinsicBounds(
        paymentOption.drawableResourceId,
        0,
        0,
        0
      )
    } else {
      paymentMethodButton.text = "Select"
      paymentMethodButton.setCompoundDrawablesRelativeWithIntrinsicBounds(
        null,
        null,
        null,
        null
      )
    }
  }
```

1. Por fim, chame [confirm](https://stripe.dev/stripe-android/paymentsheet/com.stripe.android.paymentsheet/-payment-sheet/-flow-controller/index.html#-479056656%2FFunctions%2F2002900378) para finalizar o pagamento. Quando o cliente termina, a descrição da compra é descartada e chama o [paymentResultCallback](https://stripe.dev/stripe-android/paymentsheet/com.stripe.android.paymentsheet/-payment-sheet-result-callback/index.html#237248767%2FFunctions%2F2002900378) passado anteriormente em `create`.

#### Android (Kotlin)

```kotlin
  // ...
    flowController.confirmPayment()
  // ...

  private fun onPaymentSheetResult(
    paymentSheetResult: PaymentSheetResult
  ) {
    when (paymentSheetResult) {
      is PaymentSheetResult.Canceled -> {
        // Payment canceled
      }
      is PaymentSheetResult.Failed -> {
        // Payment Failed. See logcat for details or inspect paymentSheetResult.error
      }
      is PaymentSheetResult.Completed -> {
        // Payment Complete
      }
    }
  }
```

Configurar `allowsDelayedPaymentMethods` como verdadeiro permite formas de pagamento de [notificação assíncrona](https://docs.stripe.com/payments/payment-methods.md#payment-notification) 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.


# Somente Element Card

> This is a Somente Element Card for when platform is android and mobile-ui is card-element. View the full page at https://docs.stripe.com/connect/end-to-end-marketplace?platform=android&mobile-ui=card-element.

Colete dados de cartão com segurança no cliente usando o [CardInputWidget](https://stripe.dev/stripe-android/stripe/com.stripe.android.view/-card-input-widget/index.html), um componente de IU inserível fornecido pelo SDK que coleta número do cartão, data de validade, CVC e código postal
![](https://d37ugbyn3rpeym.cloudfront.net/docs/mobile/android/android-card-input-widget-with-postal.mp4)
Este guia mostra como aceitar pagamentos e movimentar fundos para as contas bancárias dos seus vendedores ou prestadores de serviços. Para fins de demonstração, criaremos um marketplace de locações residenciais que conecta proprietários a pessoas que querem alugar um imóvel. Você pode usar os conceitos deste guia para outras situações.

## Pré-requisitos

1. [Cadastre sua plataforma](https://dashboard.stripe.com/connect).
1. [Verifique e adicione os dados da empresa no Dashboard](https://dashboard.stripe.com/account/onboarding).
1. [Conclua seu perfil da plataforma](https://dashboard.stripe.com/connect/settings/profile).
1. [Personalize as configurações da sua marca](https://dashboard.stripe.com/settings/connect/stripe-dashboard/branding). Adicione um nome de empresa, ícone e cor da marca.

## Configurar a Stripe [Lado do servidor] [Lado do cliente]

Primeiro, você precisa de uma conta Stripe. [Inscreva-se aqui](https://dashboard.stripe.com/register).

### Lado do servidor

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

#### Ruby

```bash
# Available as a gem
sudo gem install stripe
```

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

### Lado do cliente

O [SDK da Stripe para Android](https://github.com/stripe/stripe-android) é de código aberto e [totalmente documentado](https://stripe.dev/stripe-android/).

Para instalar o SDK, adicione `stripe-android` ao bloco `dependencies` do arquivo [app/build.gradle](https://developer.android.com/studio/build/dependencies):

#### Kotlin

```kotlin
plugins {
    id("com.android.application")
}

android { ... }

dependencies {
  // ...

  // Stripe Android SDK
  implementation("com.stripe:stripe-android:23.5.0")
  // Include the financial connections SDK to support US bank account as a payment method
  implementation("com.stripe:financial-connections:23.5.0")
}
```

> Veja mais informações sobre o último lançamento de SDK e as versões anteriores na página [Lançamentos](https://github.com/stripe/stripe-android/releases) no GitHub. Para receber notificações quando um novo lançamento for publicado, [assista aos lançamentos do repositório](https://docs.github.com/en/github/managing-subscriptions-and-notifications-on-github/configuring-notifications#configuring-your-watch-settings-for-an-individual-repository).

Configure o SDK com sua [chave publicável](https://dashboard.stripe.com/apikeys) da Stripe, de modo que seja possível fazer solicitações à API Stripe, como em sua subcategoria `Application`:

#### Kotlin

```kotlin
import com.stripe.android.PaymentConfiguration

class MyApp : Application() {
    override fun onCreate() {
        super.onCreate()
        PaymentConfiguration.init(
            applicationContext,
            "<<YOUR_PUBLISHABLE_KEY>>"
        )
    }
}
```

> Use suas [chaves de teste](https://docs.stripe.com/keys.md#obtain-api-keys) enquanto testa e desenvolve, e suas chaves de [modo de produção](https://docs.stripe.com/keys.md#test-live-modes) quando publicar seu aplicativo.

Nossas amostras de código também usam [OkHttp](https://github.com/square/okhttp) e [GSON](https://github.com/google/gson) para fazer solicitações HTTP a um servidor.

## Criar uma conta conectada

#### Accounts v2

Quando um vendedor ou provedor de serviços se cadastra na sua plataforma, crie uma [conta conectada](https://docs.stripe.com/api/v2/core/accounts.md) que o represente. A conta conectada permite que você recolha suas informações de identificação, aceite pagamentos para eles e transfira fundos para a conta bancária deles. Em nosso exemplo de aluguel de casas, a conta conectada representa o proprietário da casa.

#### Accounts v1

Quando um vendedor ou provedor de serviços se cadastra na sua plataforma, crie uma [conta conectada](https://docs.stripe.com/api/accounts.md) que o represente. A conta conectada permite que você recolha suas informações de identificação, aceite pagamentos para eles e transfira fundos para a conta bancária deles. Em nosso exemplo de aluguel de casas, a conta conectada representa o proprietário da casa.
![](https://b.stripecdn.com/docs-statics-srv/assets/express-android.d13776fc7e474c2a0168a705f85b11cb.png)

> Este guia usa contas Express com determinadas [restrições](https://docs.stripe.com/connect/express-accounts.md#prerequisites-for-using-express). Você também tem a opção de avaliar [contas Custom](https://docs.stripe.com/connect/custom-accounts.md).

### Crie uma conta conectada com informações pré-preenchidas (Server-side)

#### Accounts v2

Use a API `/v2/core/accounts` para [criar](https://docs.stripe.com/api/v2/core/accounts/create.md) uma conta conectada, especificando o [dashboard da conta conectada e as responsabilidades](https://docs.stripe.com/connect/accounts-v2/connected-account-configuration.md).

```curl
curl -X POST https://api.stripe.com/v2/core/accounts \
  -H "Authorization: Bearer <<YOUR_SECRET_KEY>>" \
  -H "Stripe-Version: 2026-01-28.clover" \
  --json '{
    "contact_email": "furever_contact@example.com",
    "display_name": "Furever",
    "defaults": {
        "responsibilities": {
            "fees_collector": "application",
            "losses_collector": "application"
        }
    },
    "dashboard": "express",
    "identity": {
        "business_details": {
            "registered_name": "Furever"
        },
        "country": "us",
        "entity_type": "company"
    },
    "configuration": {
        "merchant": {
            "capabilities": {
                "card_payments": {
                    "requested": true
                }
            }
        },
        "recipient": {
            "capabilities": {
                "stripe_balance": {
                    "stripe_transfers": {
                        "requested": true
                    }
                }
            }
        }
    },
    "include": [
        "configuration.merchant",
        "configuration.recipient",
        "identity",
        "requirements"
    ]
  }'
```

Se você já coletou dados de suas contas conectadas, pode usá-los para preencher o objeto `Account`. Você pode preencher quaisquer dados de conta, inclusive dados pessoais e comerciais, dados de contas externas e muito mais.

Após criar uma `Conta`, crie uma [Pessoa](https://docs.stripe.com/api/v2/core/persons/create.md) para representar a pessoa responsável por abrir a conta, definindo como verdadeiro `relationship.representative` e todas as informações da conta que você queira preencher previamente (por exemplo, o nome e sobrenome).

```curl
curl -X POST https://api.stripe.com/v2/core/accounts/{{ACCOUNT_ID}}/persons \
  -H "Authorization: Bearer <<YOUR_SECRET_KEY>>" \
  -H "Stripe-Version: 2026-04-22.preview" \
  --json '{
    "given_name": "Jenny",
    "surname": "Rosen",
    "email": "jenny.rosen@example.com",
    "relationship": {
        "representative": true
    }
  }'
```

O Connect Onboarding não solicita as informações pré-preenchidas. No entanto, ele solicita que o titular da conta confirme as informações pré-preenchidas antes de aceitar o [contrato de serviços do Connect](https://docs.stripe.com/connect/service-agreement-types.md).

Ao testar sua integração, preencha antecipadamente os dados da conta usando [dados de teste](https://docs.stripe.com/connect/testing.md).

### Criar um link da conta

Você pode criar um link de conta chamando a API [Account Links v2](https://docs.stripe.com/api/v2/core/account-links.md) com os seguintes parâmetros:

- `account`
- `refresh_url`
- `return_url`
- `type` = `account_onboarding`
- `configurations` = `recipient` e `merchant`

```curl
curl -X POST https://api.stripe.com/v2/core/account_links \
  -H "Authorization: Bearer <<YOUR_SECRET_KEY>>" \
  -H "Stripe-Version: 2025-08-27.preview" \
  --json '{
    "account": "{{CONNECTEDACCOUNT_ID}}",
    "use_case": {
        "type": "account_onboarding",
        "account_onboarding": {
            "configurations": [
                "recipient",
                "merchant"
            ],
            "refresh_url": "https://example.com/reauth",
            "return_url": "https://example.com/return"
        }
    }
  }'
```

### Redirecionar o usuário ao URL do link da conta

A resposta de criação do link da conta inclui um valor de `url`. Após autenticar o usuário no seu aplicativo, redirecione-o para essa URL para inseri-lo no fluxo. As URLs de link da conta são temporárias e de uso único, pois concedem acesso às informações pessoais do usuário da conta conectada. Se desejar preencher previamente as informações, deverá preencher antes de gerar o link da conta. Depois de criar o link da conta, não será possível ler nem gravar informações na conta conectada.

> Não envie URLs de links de conta por e-mail, SMS ou outra maneira para fora do aplicativo da sua plataforma. Em vez disso, forneça-os ao titular da conta autenticado dentro do seu aplicativo.

#### Item 1

#### Swift

```swift
import UIKit
import SafariServices

let BackendAPIBaseURL: String = "" // Set to the URL of your backend server

class ConnectOnboardViewController: UIViewController {

    // ...

    override func viewDidLoad() {
        super.viewDidLoad()

        let connectWithStripeButton = UIButton(type: .system)
        connectWithStripeButton.setTitle("Connect with Stripe", for: .normal)
        connectWithStripeButton.addTarget(self, action: #selector(didSelectConnectWithStripe), for: .touchUpInside)
        view.addSubview(connectWithStripeButton)

        // ...
    }

    @objc
    func didSelectConnectWithStripe() {
        if let url = URL(string: BackendAPIBaseURL)?.appendingPathComponent("onboard-user") {
          var request = URLRequest(url: url)
          request.httpMethod = "POST"
          let task = URLSession.shared.dataTask(with: request) { (data, response, error) in
              guard let data = data,
                  let json = try? JSONSerialization.jsonObject(with: data, options: []) as? [String : Any],
                  let accountURLString = json["url"] as? String,
                  let accountURL = URL(string: accountURLString) else {
                      // handle error
              }

              let safariViewController = SFSafariViewController(url: accountURL)
              safariViewController.delegate = self

              DispatchQueue.main.async {
                  self.present(safariViewController, animated: true, completion: nil)
              }
          }
        }
    }

    // ...
}

extension ConnectOnboardViewController: SFSafariViewControllerDelegate {
    func safariViewControllerDidFinish(_ controller: SFSafariViewController) {
        // the user may have closed the SFSafariViewController instance before a redirect
        // occurred. Sync with your backend to confirm the correct state
    }
}

```

#### Item 2

```xml
<?xml version="1.0" encoding="utf-8"?>
<androidx.constraintlayout.widget.ConstraintLayout
    xmlns:android="http://schemas.android.com/apk/res/android"
    xmlns:app="http://schemas.android.com/apk/res-auto"
    xmlns:tools="http://schemas.android.com/tools"
    android:layout_width="match_parent"
    android:layout_height="match_parent"
    tools:context=".activity.ConnectWithStripeActivity">

    <Button
        android:id="@+id/connect_with_stripe"
        android:text="Connect with Stripe"
        android:layout_height="wrap_content"
        android:layout_width="wrap_content"
        app:layout_constraintBottom_toBottomOf="parent"
        app:layout_constraintEnd_toEndOf="parent"
        app:layout_constraintStart_toStartOf="parent"
        app:layout_constraintTop_toTopOf="parent"
        style="?attr/materialButtonOutlinedStyle"
        />

</androidx.constraintlayout.widget.ConstraintLayout>
```

#### Kotlin

```kotlin
class ConnectWithStripeActivity : AppCompatActivity() {

    private val viewBinding: ActivityConnectWithStripeViewBinding by lazy {
        ActivityConnectWithStripeViewBinding.inflate(layoutInflater)
    }
    private val httpClient = OkHttpClient()

    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        setContentView(viewBinding.root)

        viewBinding.connectWithStripe.setOnClickListener {
            val weakActivity = WeakReference<Activity>(this)
            val request = Request.Builder()
                .url(BACKEND_URL + "onboard-user")
                .post("".toRequestBody())
                .build()
            httpClient.newCall(request)
                .enqueue(object: Callback {
                    override fun onFailure(call: Call, e: IOException) {
                        // Request failed
                    }
                    override fun onResponse(call: Call, response: Response) {
                        if (!response.isSuccessful) {
                            // Request failed
                        } else {
                            val responseData = response.body?.string()
                            val responseJson =
                                responseData?.let { JSONObject(it) } ?: JSONObject()
                            val url = responseJson.getString("url")

                            weakActivity.get()?.let {
                                val builder: CustomTabsIntent.Builder = CustomTabsIntent.Builder()
                                val customTabsIntent = builder.build()
                                customTabsIntent.launchUrl(it, Uri.parse(url))
                            }
                        }
                    }
                })
        }
    }

    internal companion object {
        internal const val BACKEND_URL = "https://example-backend-url.com/"
    }
}
```

#### Item 3

### Gerenciar o usuário que volta à plataforma

O Connect Onboarding exige que você passe tanto um `return_url` quanto um `refresh_url` para lidar com todos os casos em que o usuário da conta é redirecionado para a sua plataforma.

> Você pode usar HTTP para seu `return_url` e para o `refresh_url` enquanto estiver em um ambiente de teste (por exemplo, para testar com o localhost), mas modo de produção aceita apenas HTTPS. Você deve atualizar URLs de teste para URLs HTTPS antes do lançamento.

#### return_url

A Stripe emite um redirecionamento para essa URL quando o usuário da conta conectada conclui o fluxo de onboarding. Isso não significa que todas as informações tenham sido recolhidas ou que não haja requisitos pendentes na conta. Significa apenas que o fluxo foi inserido e encerrado corretamente.

Nenhum estado é transmitido por essa URL. Depois que um usuário for redirecionado para o seu `return_url`, verifique o estado dos requisitos na conta dele fazendo o seguinte:

- Ouça os Webhooks `v2.core.account[requirements].updated`.
- Chame a API [Accounts v2](https://docs.stripe.com/api/v2/core/accounts/retrieve.md) e inspecione o objeto retornado.

#### refresh_url

A Stripe redireciona seu usuário para o `refresh_url` nestes casos:

- O link expirou (alguns minutos se passaram desde a criação do link).
- O usuário já acessou o URL (atualizou a página ou clicou em Voltar ou Avançar no navegador).
- Sua plataforma não consegue mais acessar a conta.
- A conta foi recusada.

Configure sua página `refresh_url` para acionar um método em seu servidor para chamar [Account Links v2](https://docs.stripe.com/api/v2/core/account-links.md) novamente com os mesmos parâmetros e redirecionar o usuário para o novo link.

### Gerenciar usuários que não concluíram o onboarding

Um usuário redirecionado para o seu `return_url` pode não ter concluído o processo de onboarding. Use o endpoint `/v2/core/accounts` para recuperar a conta do usuário e verificar se [configuration.recipient.capabilities.stripe_balance.stripe_transfers.status](https://docs.stripe.com/api/v2/core/accounts/object.md#v2_account_object-configuration-recipient-capabilities-stripe_balance-stripe_transfers-status) está coo `active`. Se o status não estiver `active` e [configuration.destinatário.capabilities.stripe_balance.stripe_transfers.status_details.code](https://docs.stripe.com/api/v2/core/accounts/object.md#v2_account_object-configuration-recipient-capabilities-stripe_balance-stripe_transfers-status_details-code) for `requirements_past_due`, forneça prompts na IU para permitir que o usuário continue o onboarding por meio de um novo link de conta. Para outros códigos, trate-os conforme necessário.

#### Accounts v1

Use a API `/v1/accounts` para [criar](https://docs.stripe.com/api/accounts/create.md) uma conta conectada especificando as [propriedades da conta conectada](https://docs.stripe.com/connect/migrate-to-controller-properties.md) ou o tipo de conta.

```curl
curl https://api.stripe.com/v1/accounts \
  -u "<<YOUR_SECRET_KEY>>:" \
  -d "controller[losses][payments]=application" \
  -d "controller[fees][payer]=application" \
  -d "controller[stripe_dashboard][type]=express"
```

Se você já coletou dados de suas contas conectadas, pode usá-los para preencher o objeto `Account`. Você pode preencher quaisquer dados de conta, inclusive dados pessoais e comerciais, dados de contas externas e muito mais.

Depois de criar uma `Account`, crie uma [Pessoa](https://docs.stripe.com/api/persons/create.md) para representar a pessoa responsável por abrir a conta, com `relationship.representative` definido como verdadeiro e informações da conta que você queira preencher previamente (por exemplo, o nome e sobrenome).

```curl
curl https://api.stripe.com/v1/accounts/{{ACCOUNT_ID}}/persons \
  -u "<<YOUR_SECRET_KEY>>:" \
  -d first_name=Jenny \
  -d last_name=Rosen \
  -d "relationship[representative]=true"
```

O Connect Onboarding não solicita as informações pré-preenchidas. No entanto, ele solicita que o titular da conta confirme as informações pré-preenchidas antes de aceitar o [contrato de serviços do Connect](https://docs.stripe.com/connect/service-agreement-types.md).

Ao testar sua integração, preencha antecipadamente os dados da conta usando [dados de teste](https://docs.stripe.com/connect/testing.md).

### Criar um link da conta

Você pode criar um link de conta chamando a API [Account Links v1](https://docs.stripe.com/api/account_links.md) com os seguintes parâmetros:

- `account`
- `refresh_url`
- `return_url`
- `type` = `account_onboarding`

```curl
curl https://api.stripe.com/v1/account_links \
  -u "<<YOUR_SECRET_KEY>>:" \
  -d "account={{CONNECTEDACCOUNT_ID}}" \
  --data-urlencode "refresh_url=https://example.com/reauth" \
  --data-urlencode "return_url=https://example.com/return" \
  -d type=account_onboarding
```

### Redirecionar o usuário ao URL do link da conta

A resposta da criação do link da conta inclui um valor de `url`. Após autenticar o usuário no seu aplicativo, redirecione-o para esta URL para inseri-lo no fluxo. As URLs de links de conta da [API Account Links v1](https://docs.stripe.com/api/account_links.md) são temporárias e de uso único, pois concedem acesso às informações pessoais do usuário da conta conectada. Autentique o usuário no seu aplicativo antes de redirecioná-lo para esta URL. Se desejar preencher previamente as informações, deverá preencher antes de gerar o link da conta. Depois de criar o link da conta, não será possível ler nem gravar informações da conta conectada.

> Não envie URLs de links de conta por e-mail, SMS ou outra maneira para fora do aplicativo da sua plataforma. Em vez disso, forneça-os ao titular da conta autenticado dentro do seu aplicativo.

#### Item 1

#### Swift

```swift
import UIKit
import SafariServices

let BackendAPIBaseURL: String = "" // Set to the URL of your backend server

class ConnectOnboardViewController: UIViewController {

    // ...

    override func viewDidLoad() {
        super.viewDidLoad()

        let connectWithStripeButton = UIButton(type: .system)
        connectWithStripeButton.setTitle("Connect with Stripe", for: .normal)
        connectWithStripeButton.addTarget(self, action: #selector(didSelectConnectWithStripe), for: .touchUpInside)
        view.addSubview(connectWithStripeButton)

        // ...
    }

    @objc
    func didSelectConnectWithStripe() {
        if let url = URL(string: BackendAPIBaseURL)?.appendingPathComponent("onboard-user") {
          var request = URLRequest(url: url)
          request.httpMethod = "POST"
          let task = URLSession.shared.dataTask(with: request) { (data, response, error) in
              guard let data = data,
                  let json = try? JSONSerialization.jsonObject(with: data, options: []) as? [String : Any],
                  let accountURLString = json["url"] as? String,
                  let accountURL = URL(string: accountURLString) else {
                      // handle error
              }

              let safariViewController = SFSafariViewController(url: accountURL)
              safariViewController.delegate = self

              DispatchQueue.main.async {
                  self.present(safariViewController, animated: true, completion: nil)
              }
          }
        }
    }

    // ...
}

extension ConnectOnboardViewController: SFSafariViewControllerDelegate {
    func safariViewControllerDidFinish(_ controller: SFSafariViewController) {
        // the user may have closed the SFSafariViewController instance before a redirect
        // occurred. Sync with your backend to confirm the correct state
    }
}

```

#### Item 2

```xml
<?xml version="1.0" encoding="utf-8"?>
<androidx.constraintlayout.widget.ConstraintLayout
    xmlns:android="http://schemas.android.com/apk/res/android"
    xmlns:app="http://schemas.android.com/apk/res-auto"
    xmlns:tools="http://schemas.android.com/tools"
    android:layout_width="match_parent"
    android:layout_height="match_parent"
    tools:context=".activity.ConnectWithStripeActivity">

    <Button
        android:id="@+id/connect_with_stripe"
        android:text="Connect with Stripe"
        android:layout_height="wrap_content"
        android:layout_width="wrap_content"
        app:layout_constraintBottom_toBottomOf="parent"
        app:layout_constraintEnd_toEndOf="parent"
        app:layout_constraintStart_toStartOf="parent"
        app:layout_constraintTop_toTopOf="parent"
        style="?attr/materialButtonOutlinedStyle"
        />

</androidx.constraintlayout.widget.ConstraintLayout>
```

#### Kotlin

```kotlin
class ConnectWithStripeActivity : AppCompatActivity() {

    private val viewBinding: ActivityConnectWithStripeViewBinding by lazy {
        ActivityConnectWithStripeViewBinding.inflate(layoutInflater)
    }
    private val httpClient = OkHttpClient()

    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        setContentView(viewBinding.root)

        viewBinding.connectWithStripe.setOnClickListener {
            val weakActivity = WeakReference<Activity>(this)
            val request = Request.Builder()
                .url(BACKEND_URL + "onboard-user")
                .post("".toRequestBody())
                .build()
            httpClient.newCall(request)
                .enqueue(object: Callback {
                    override fun onFailure(call: Call, e: IOException) {
                        // Request failed
                    }
                    override fun onResponse(call: Call, response: Response) {
                        if (!response.isSuccessful) {
                            // Request failed
                        } else {
                            val responseData = response.body?.string()
                            val responseJson =
                                responseData?.let { JSONObject(it) } ?: JSONObject()
                            val url = responseJson.getString("url")

                            weakActivity.get()?.let {
                                val builder: CustomTabsIntent.Builder = CustomTabsIntent.Builder()
                                val customTabsIntent = builder.build()
                                customTabsIntent.launchUrl(it, Uri.parse(url))
                            }
                        }
                    }
                })
        }
    }

    internal companion object {
        internal const val BACKEND_URL = "https://example-backend-url.com/"
    }
}
```

### Gerenciar o usuário que volta à plataforma

O Connect Onboarding exige que você passe um `return_url` e `refresh_url` para gerenciar todos os casos em que o usuário é redirecionado à sua plataforma. É importante implementá-los corretamente para proporcionar a melhor experiência ao usuário.

> Você pode usar HTTP para seu `return_url` e para o `refresh_url` enquanto estiver em um ambiente de teste (por exemplo, para testar com o localhost), mas modo de produção aceita apenas HTTPS. Você deve atualizar URLs de teste para URLs HTTPS antes do lançamento.

#### return_url

A Stripe emite um redirecionamento para essa URL quando o usuário da conta conectada conclui o fluxo de onboarding. Isso não significa que todas as informações tenham sido recolhidas ou que não haja requisitos pendentes na conta. Significa apenas que o fluxo foi inserido e encerrado corretamente.

Nenhum estado é passado por este URL. Após o redirecionamento de um usuário para o `return_url` , verifique o estado do parâmetro `details_submitted` na conta dele realizando uma das seguintes ações:

- Ouça os Webhooks `account.updated`
- Chame a API [Accounts v1](https://docs.stripe.com/api/accounts.md) e inspecione o objeto retornado

#### refresh_url

A Stripe redireciona seu usuário para o `refresh_url` nestes casos:

- O link expirou (alguns minutos se passaram desde a criação do link).
- O usuário já acessou o URL (atualizou a página ou clicou em Voltar ou Avançar no navegador).
- Sua plataforma não consegue mais acessar a conta.
- A conta foi recusada.

Configure sua página `refresh_url` para acionar um método em seu servidor para chamar [Account Links v1](https://docs.stripe.com/api/account_links.md) novamente com os mesmos parâmetros e redirecionar o usuário para o novo link.

### Gerenciar usuários que não concluíram o onboarding

Um usuário que é redirecionado para seu `return_url` pode não ter concluído o processo de onboarding. Use o endpoint `/v1/accounts` para recuperar a conta do usuário e verificar se `charges_enabled`. Se a conta não estiver totalmente integrada, forneça prompts de IU para permitir que o usuário continue fazendo onboarding por meio de um novo link de conta. Você pode determinar se eles concluíram o onboarding verificando o estado do parâmetro `details_submitted` na conta deles.

## Aceitar um pagamento

### Etapa 3.1: Crie uma página de checkout (Lado do cliente)

Colete dados de cartão com segurança no cliente usando o [CardInputWidget](https://stripe.dev/stripe-android/payments-core/com.stripe.android.view/-card-input-widget/index.html), um componente de IU inserível fornecido pelo SDK que coleta número do cartão, data de validade, CVC e código postal
![](https://d37ugbyn3rpeym.cloudfront.net/docs/mobile/android/android-card-input-widget-with-postal.mp4)
Crie uma instância do componente de cartão e um botão **Pagar**, acrescentando o seguinte ao layout de sua página de checkout:

```xml
<?xml version="1.0" encoding="utf-8"?>

<LinearLayout
    xmlns:android="http://schemas.android.com/apk/res/android"
    xmlns:tools="http://schemas.android.com/tools"
    android:layout_width="match_parent"
    android:layout_height="match_parent"
    android:orientation="vertical"
    android:padding="20dp"
    tools:context=".CheckoutActivityKotlin"
    tools:showIn="@layout/activity_checkout">

    <!--  ...  -->

    <com.stripe.android.view.CardInputWidget
        android:id="@+id/cardInputWidget"
        android:layout_width="match_parent"
        android:layout_height="wrap_content" />

    <Button
        android:text="@string/pay"
        android:layout_width="match_parent"
        android:layout_height="wrap_content"
        android:id="@+id/payButton"
        android:layout_marginTop="20dp"
        android:backgroundTint="@android:color/holo_green_light"/>

    <!--  ...  -->

</LinearLayout>
```

Execute seu aplicativo e verifique se sua página de checkout mostra o componente de cartão e o botão de pagamento.

### Etapa 3.2: Crie um PaymentIntent (Lado do servidor) (Lado do cliente)

A Stripe usa um objeto [PaymentIntent](https://docs.stripe.com/api/payment_intents.md) 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.

### Lado do servidor

No seu servidor, crie um endpoint que cria um PaymentIntent com um [valor](https://docs.stripe.com/api/payment_intents/object.md#payment_intent_object-amount) e uma [moeda](https://docs.stripe.com/api/payment_intents/object.md#payment_intent_object-currency). Sempre decida quanto deseja cobrar no lado do servidor, um ambiente confiável, e não no lado do cliente. Isso evita que clientes mal-intencionados escolham os próprios preços.

#### curl

```bash
curl https://api.stripe.com/v1/payment_intents \
  -u <<YOUR_SECRET_KEY>>: \
  -d amount=1000 \
  -d currency="usd" \
  -d "automatic_payment_methods[enabled]"=true \
  -d application_fee_amount="123" \
  -d "transfer_data[destination]"="{{CONNECTED_STRIPE_ACCOUNT_ID}}"
```

Em nosso exemplo para aluguel residencial, queremos criar uma empresa em que os clientes pagam o aluguel em nossa plataforma, e nós repassamos o aluguel aos locatários. Para configurar esta empresa:

- Indique que o aluguel é uma cobrança de destino, com `transfer_data[destination]`.
- Especifique em `application_fee_amount` o valor que será pago à plataforma.

Ao cobrar um aluguel, a Stripe transfere o valor total para o saldo em aberto da conta conectada (`transfer_data[destination]`). Em seguida, a Stripe transfere a tarifa (`application_fee_amount`) para a conta da plataforma (uma participação na receita, pela intermediação do aluguel). Por fim, são deduzidas as tarifas da Stripe do valor da tarifa da plataforma. Veja esse fluxo ilustrado abaixo:
![](https://b.stripecdn.com/docs-statics-srv/assets/application_fee_amount.837aa2339469b3c1a4319672971c1367.svg)

> Este PaymentIntent cria uma cobrança de destino. Se você quiser controlar o cronograma das transferências ou precisar transferir fundos de um único pagamento para várias partes, use [cobranças e transferências separadas](https://docs.stripe.com/connect/separate-charges-and-transfers.md).

Em vez de passar todo o objeto PaymentIntent para o seu aplicativo, retorne somente o *client secret* (The client secret is a unique key returned from Stripe as part of a PaymentIntent. This key lets the client access important fields from the PaymentIntent (status, amount, currency) while hiding sensitive ones (metadata, customer)). A chave secreta do cliente do PaymentIntent é uma chave única que permite confirmar o pagamento e atualizar dados do cartão do cliente, mas impede a manipulação de informações confidenciais, como o valor do pagamento.

### Lado do cliente

No cliente, solicite um PaymentIntent a partir do seu servidor e armazene o *segredo de cliente* (The client secret is a unique key returned from Stripe as part of a PaymentIntent. This key lets the client access important fields from the PaymentIntent (status, amount, currency) while hiding sensitive ones (metadata, customer)).

#### Kotlin

```kotlin
class CheckoutActivity : AppCompatActivity() {

  private lateinit var paymentIntentClientSecret: String

  override fun onCreate(savedInstanceState: Bundle?) {
      super.onCreate(savedInstanceState)
      // ...
      startCheckout()
  }

  private fun startCheckout() {
      // Request a PaymentIntent from your server and store its client secret in paymentIntentClientSecret
      // Click View full sample to see a complete implementation
  }
}
```

### Etapa 3.3: Envie o pagamento à Stripe (Lado do cliente)

Quando o cliente toca no botão **Pagar**, *confirme* (Confirming a PaymentIntent indicates that the customer intends to pay with the current or provided payment method. Upon confirmation, the PaymentIntent attempts to initiate a payment) o `PaymentIntent` para finalizar o pagamento.

Primeiro, monte um objeto [ConfirmPaymentIntentParams](https://stripe.dev/stripe-android/payments-core/com.stripe.android.model/-confirm-payment-intent-params/index.html) com:

1. Os dados da forma de pagamento do componente do cartão
1. O segredo do cliente do `PaymentIntent` do seu servidor

Em vez de enviar o objeto PaymentIntent para o cliente, use o *segredo do cliente* (The client secret is a unique key returned from Stripe as part of a PaymentIntent. This key lets the client access important fields from the PaymentIntent (status, amount, currency) while hiding sensitive ones (metadata, customer)), que é diferente das chaves de API que autenticam solicitações da API Stripe. O segredo do cliente é uma string que permite que o aplicativo acesse campos importantes do PaymentIntent (por exemplo, `status`), mas oculta campos confidenciais (como `customer`).

Administre cuidadosamente o segredo do cliente, pois ele pode finalizar a cobrança. Não registre em log, incorpore a URLs nem exponha esse nome a ninguém, exceto ao cliente.

Em seguida, chame o método [PaymentLauncher confirm](https://stripe.dev/stripe-android/payments-core/com.stripe.android.payments.paymentlauncher/-payment-launcher/index.html#74063765%2FFunctions%2F-1622557690) para finalizar o pagamento.

#### Kotlin

```kotlin
class CheckoutActivity : AppCompatActivity() {
    // ...
    private lateinit var paymentIntentClientSecret: String
    private lateinit var paymentLauncher: PaymentLauncher

    private fun startCheckout() {
        // ...

        // Hook up the pay button to the card widget and stripe instance
        val payButton: Button = findViewById(R.id.payButton)
        payButton.setOnClickListener {
            val params = cardInputWidget.paymentMethodCreateParams
            if (params != null) {
                val confirmParams = ConfirmPaymentIntentParams
                    .createWithPaymentMethodCreateParams(params, paymentIntentClientSecret)
                val paymentConfiguration = PaymentConfiguration.getInstance(applicationContext)
                paymentLauncher = PaymentLauncher.Companion.create(
                    this,
                    paymentConfiguration.publishableKey,
                    paymentConfiguration.stripeAccountId,
                    ::onPaymentResult
                )
                paymentLauncher.confirm(confirmParams)
            }
        }
    }

    private fun onPaymentResult(paymentResult: PaymentResult) {
        val message = when (paymentResult) {
            is PaymentResult.Completed -> {
                "Completed!"
            }
            is PaymentResult.Canceled -> {
                "Canceled!"
            }
            is PaymentResult.Failed -> {
                // This string comes from the PaymentIntent's error message.
                // See here: https://stripe.com/docs/api/payment_intents/object#payment_intent_object-last_payment_error-message
                "Failed: " + paymentResult.throwable.message
            }
        }
        displayAlert(
            "PaymentResult: ",
            message,
            restartDemo = true
        )
    }
}
```

Você pode [salvar os dados do cartão de pagamento de um cliente](https://docs.stripe.com/payments/payment-intents.md#future-usage) na confirmação do pagamento informando `setupFutureUsage` e um `customer` no `PaymentIntent`. Você também pode informar esses parâmetros ao criar o `PaymentIntent` no servidor.

Para informar um valor adequado em `setupFutureUsage` para o aplicativo, pode ser necessário que o cliente faça outras autenticações, mas reduz a probabilidade de recusa de pagamentos futuros pelos bancos. [Saiba como otimizar cartões para pagamentos futuros](https://docs.stripe.com/payments/payment-intents.md#future-usage) e determine qual valor usar para seu aplicativo.

| Como você pretende usar o cartão                                                                                                                                                             | Valor de enumeração `setup_future_usage` |
| -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------- |
| Somente para pagamentos *na sessão* (A payment is described as on-session if it occurs while the customer is actively in your checkout flow and able to authenticate the payment method)     | `on_session`                             |
| Somente para pagamentos *fora da sessão* (A payment is described as off-session if it occurs without the direct involvement of the customer, using previously-collected payment information) | `off_session`                            |
| Pagamentos na sessão ou fora da sessão                                                                                                                                                       | `off_session`                            |

Você pode usar um cartão configurado para pagamentos na sessão para fazer pagamentos fora da sessão, mas é mais provável que o banco recuse o pagamento fora da sessão e exija autenticação do titular do cartão.

Quando regulamentos como a [Autenticação Forte de Cliente](https://docs.stripe.com/strong-customer-authentication.md) exigem autenticação, o SDK apresenta outras atividades e orienta o cliente nesse processo. [Saiba como aceitar a autenticação do 3D Secure no Android](https://docs.stripe.com/payments/3d-secure.md?platform=android).

Quando o pagamento é finalizado, `onSuccess` é chamado e o valor do `status` do `PaymentIntent` retornado é `Succeeded`. Qualquer valor diferente indica que o pagamento não foi bem-sucedido. Inspecione [lastPaymentError](https://stripe.dev/stripe-android/payments-core/com.stripe.android.model/-payment-intent/index.html#com.stripe.android.model/PaymentIntent/lastPaymentError/#/PointingToDeclaration/) para descobrir a causa.

Também é possível verificar o status de um `PaymentIntent` no [Dashboard](https://dashboard.stripe.com/test/payments) ou inspecionando a propriedade `status` no objeto.

### Etapa 3.4: Teste a integração (Lado do cliente)

​​Vários cartões de teste estão disponíveis para você usar em uma área restrita para assegurar que essa integração esteja pronta. Use-os com qualquer CVC e uma data de validade no futuro.

| Número           | Descrição                                                                                    |
| ---------------- | -------------------------------------------------------------------------------------------- |
| 4242424242424242 | Finaliza e processa o pagamento imediatamente.                                               |
| 4000002500003155 | Requer autenticação. A Stripe abre uma janela solicitando que o cliente faça a autenticação. |
| 4000000000009995 | Sempre falha, com o código de recusa `insufficient_funds`.                                   |

Veja a lista completa de cartões de teste em nosso guia de [testes](https://docs.stripe.com/testing.md).

### Etapa 3.5: Execução (Lado do servidor)

Após a conclusão do pagamento, é preciso gerenciar qualquer *execução* (Fulfillment is the process of providing the goods or services purchased by a customer, typically after payment is collected) necessária. Uma empresa de aluguel residencial que exige pagamento antecipado, por exemplo, conectaria o proprietário ao locatário após um pagamento realizado.

Configure um endpoint de *webhook* (A webhook is a real-time push notification sent to your application as a JSON payload through HTTPS requests) (para eventos *de sua conta*) [no Dashboard](https://dashboard.stripe.com/account/webhooks).
![](https://b.stripecdn.com/docs-statics-srv/assets/account_webhooks.03b71cec87ef2093fe0caa92e5bfce44.png)

Em seguida, crie um endpoint de HTTP no seu servidor para monitorar pagamentos concluídos para habilitar seus vendedores ou prestadores de serviços a processar compras. Certifique-se de substituir a chave secreta do endpoint (`whsec_...`) no exemplo com sua chave.

#### Rubi

```ruby
# Using Sinatra.
require 'sinatra'
require 'stripe'

set :port, 4242

# Don't put any keys in code. See https://docs.stripe.com/keys-best-practices.
# Find your keys at https://dashboard.stripe.com/apikeys.
client = Stripe::StripeClient.new('<<YOUR_SECRET_KEY>>')

# If you are testing your webhook locally with the Stripe CLI you
# can find the endpoint's secret by running `stripe listen`
# Otherwise, find your endpoint's secret in your webhook settings in
# the Developer Dashboard
endpoint_secret = 'whsec_...'

post '/webhook' do
  payload = request.body.read
  sig_header = request.env['HTTP_STRIPE_SIGNATURE']

  event = nil
# Verify webhook signature and extract the event.
  # See https://stripe.com/docs/webhooks#verify-events for more information.
  begin
    event = Stripe::Webhook.construct_event(
      payload, sig_header, endpoint_secret
    )
  rescue JSON::ParserError => e
    # Invalid payload.
    status 400
    return
  rescue Stripe::SignatureVerificationError => e
    # Invalid Signature.
    status 400
    return
  end

  if event['type'] == 'payment_intent.succeeded'
    payment_intent = event['data']['object']
    handle_successful_payment_intent(payment_intent)
  end

  status 200
end

def handle_successful_payment_intent(payment_intent)
  # Fulfill the purchase
  puts payment_intent.to_s
end
```

Saiba mais no nosso [guia de execução para pagamentos](https://docs.stripe.com/webhooks/handling-payment-events.md).

### Testar webhooks localmente

Use a Stripe CLI para testar webhooks localmente.

1. Primeiro [instale o Stripe CLI](https://docs.stripe.com/stripe-cli/install.md) na sua máquina, caso ainda não tenha instalado.

1. Para fazer login, execute `stripe login` na linha de comando e siga as instruções.

1. Por fim, para permitir que seu host local receba um evento simulado em sua conta conectada, execute `stripe listen --forward-to localhost:{PORT}/webhook` em uma janela do terminal e execute `stripe trigger --stripe-account={{CONNECTED_STRIPE_ACCOUNT_ID}} payment_intent.succeeded` (ou acione qualquer outro [evento aceito](https://github.com/stripe/stripe-cli/wiki/trigger-command#supported-events)) em outro.

### Etapa 3.6: Contestações

Como [comerciante de liquidação](https://docs.stripe.com/connect/destination-charges.md#settlement-merchant) das cobranças, sua plataforma é responsável pelas contestações. Leia com atenção as [práticas recomendadas](https://docs.stripe.com/disputes/responding.md) para responder a contestações.

## Testes

[Crie contas](https://docs.stripe.com/connect/testing.md#creating-accounts) e use [OAuth](https://docs.stripe.com/connect/testing.md#using-oauth) para testar o fluxo de criação de contas. É possível usar [os cartões de teste disponíveis](https://docs.stripe.com/testing.md) para testar seu fluxo de pagamentos e simular vários resultados de pagamento.


# React Native

> This is a React Native for when platform is react-native and mobile-ui is payment-sheet. View the full page at https://docs.stripe.com/connect/end-to-end-marketplace?platform=react-native&mobile-ui=payment-sheet.
![](https://b.stripecdn.com/docs-statics-srv/assets/ios-overview.9e0d68d009dc005f73a6f5df69e00458.png)

Essa integração combina todas as etapas exigidas para pagar, incluindo coletar dados de pagamento e confirmar o pagamento, em uma única folha que é exibida na parte superior do seu aplicativo.

> #### Accounts v2 API support
> 
> The Payment Sheet doesn’t support *customer-configured Accounts* (Account configurations represent role-based functionality that you can enable for accounts, such as merchant, customer, or recipient). It only supports `Customer` objects.

## Pré-requisitos

1. [Cadastre sua plataforma](https://dashboard.stripe.com/connect).
1. [Verifique e adicione os dados da empresa no Dashboard](https://dashboard.stripe.com/account/onboarding).
1. [Conclua seu perfil da plataforma](https://dashboard.stripe.com/connect/settings/profile).
1. [Personalize as configurações da sua marca](https://dashboard.stripe.com/settings/connect/stripe-dashboard/branding). Adicione um nome de empresa, ícone e cor da marca.

## Configurar a Stripe [Lado do servidor] [Lado do cliente]

Primeiro, você precisa de uma conta Stripe. [Inscreva-se agora](https://dashboard.stripe.com/register).

### 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:

#### Ruby

```bash
# Available as a gem
sudo gem install stripe
```

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

### Lado do cliente

O [SDK do React Native](https://github.com/stripe/stripe-react-native) é de código aberto e totalmente documentado. Internamente, utiliza as SDKs de [iOS nativo](https://github.com/stripe/stripe-ios) e [Android](https://github.com/stripe/stripe-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

```bash
yarn add @stripe/stripe-react-native
```

#### npm

```bash
npm install @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.

> Recomendamos seguir o [guia oficial do TypeScript](https://reactnative.dev/docs/typescript#adding-typescript-to-an-existing-project) para adicionar suporte ao TypeScript.

### 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](https://docs.stripe.com/keys.md#obtain-api-keys) em `publishableKey` é necessária. O exemplo a seguir mostra como inicializar a Stripe usando o componente `StripeProvider`.

```jsx
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>
  );
}
```

> Use suas [chaves de API de teste](https://docs.stripe.com/keys.md#obtain-api-keys) enquanto testa e desenvolve, e as chaves de [modo de produção](https://docs.stripe.com/keys.md#test-live-modes) quando publica seu aplicativo.

## Criar uma conta conectada

#### Accounts v2

Quando um vendedor ou provedor de serviços se cadastra na sua plataforma, crie uma [conta conectada](https://docs.stripe.com/api/v2/core/accounts.md) que o represente. A conta conectada permite que você recolha suas informações de identificação, aceite pagamentos para eles e transfira fundos para a conta bancária deles. Em nosso exemplo de aluguel de casas, a conta conectada representa o proprietário da casa.

#### Accounts v1

Quando um vendedor ou provedor de serviços se cadastra na sua plataforma, crie uma [conta conectada](https://docs.stripe.com/api/accounts.md) que o represente. A conta conectada permite que você recolha suas informações de identificação, aceite pagamentos para eles e transfira fundos para a conta bancária deles. Em nosso exemplo de aluguel de casas, a conta conectada representa o proprietário da casa.

### Crie uma conta conectada com informações pré-preenchidas

#### Accounts v2

Use a API `/v2/core/accounts` para [criar](https://docs.stripe.com/api/v2/core/accounts/create.md) uma conta conectada, especificando o [dashboard da conta conectada e as responsabilidades](https://docs.stripe.com/connect/accounts-v2/connected-account-configuration.md).

```curl
curl -X POST https://api.stripe.com/v2/core/accounts \
  -H "Authorization: Bearer <<YOUR_SECRET_KEY>>" \
  -H "Stripe-Version: 2026-01-28.clover" \
  --json '{
    "contact_email": "furever_contact@example.com",
    "display_name": "Furever",
    "defaults": {
        "responsibilities": {
            "fees_collector": "application",
            "losses_collector": "application"
        }
    },
    "dashboard": "express",
    "identity": {
        "business_details": {
            "registered_name": "Furever"
        },
        "country": "us",
        "entity_type": "company"
    },
    "configuration": {
        "merchant": {
            "capabilities": {
                "card_payments": {
                    "requested": true
                }
            }
        },
        "recipient": {
            "capabilities": {
                "stripe_balance": {
                    "stripe_transfers": {
                        "requested": true
                    }
                }
            }
        }
    },
    "include": [
        "configuration.merchant",
        "configuration.recipient",
        "identity",
        "requirements"
    ]
  }'
```

Se você já coletou dados de suas contas conectadas, pode usá-los para preencher o objeto `Account`. Você pode preencher quaisquer dados de conta, inclusive dados pessoais e comerciais, dados de contas externas e muito mais.

Após criar uma `Conta`, crie uma [Pessoa](https://docs.stripe.com/api/v2/core/persons/create.md) para representar a pessoa responsável por abrir a conta, definindo como verdadeiro `relationship.representative` e todas as informações da conta que você queira preencher previamente (por exemplo, o nome e sobrenome).

```curl
curl -X POST https://api.stripe.com/v2/core/accounts/{{ACCOUNT_ID}}/persons \
  -H "Authorization: Bearer <<YOUR_SECRET_KEY>>" \
  -H "Stripe-Version: 2026-04-22.preview" \
  --json '{
    "given_name": "Jenny",
    "surname": "Rosen",
    "email": "jenny.rosen@example.com",
    "relationship": {
        "representative": true
    }
  }'
```

O Connect Onboarding não solicita as informações pré-preenchidas. No entanto, ele solicita que o titular da conta confirme as informações pré-preenchidas antes de aceitar o [contrato de serviços do Connect](https://docs.stripe.com/connect/service-agreement-types.md).

Ao testar sua integração, preencha antecipadamente os dados da conta usando [dados de teste](https://docs.stripe.com/connect/testing.md).

### Criar um link da conta

Você pode criar um link de conta chamando a API [Account Links v2](https://docs.stripe.com/api/v2/core/account-links.md) com os seguintes parâmetros:

- `account`
- `refresh_url`
- `return_url`
- `type` = `account_onboarding`
- `configurations` = `recipient` e `merchant`

```curl
curl -X POST https://api.stripe.com/v2/core/account_links \
  -H "Authorization: Bearer <<YOUR_SECRET_KEY>>" \
  -H "Stripe-Version: 2025-08-27.preview" \
  --json '{
    "account": "{{CONNECTEDACCOUNT_ID}}",
    "use_case": {
        "type": "account_onboarding",
        "account_onboarding": {
            "configurations": [
                "recipient",
                "merchant"
            ],
            "refresh_url": "https://example.com/reauth",
            "return_url": "https://example.com/return"
        }
    }
  }'
```

### Redirecionar o usuário ao URL do link da conta

A resposta de criação do link da conta inclui um valor de `url`. Após autenticar o usuário no seu aplicativo, redirecione-o para essa URL para inseri-lo no fluxo. As URLs de link da conta são temporárias e de uso único, pois concedem acesso às informações pessoais do usuário da conta conectada. Se desejar preencher previamente as informações, deverá preencher antes de gerar o link da conta. Depois de criar o link da conta, não será possível ler nem gravar informações na conta conectada.

> Não envie URLs de links de conta por e-mail, SMS ou outra maneira para fora do aplicativo da sua plataforma. Em vez disso, forneça-os ao titular da conta autenticado dentro do seu aplicativo.

#### Item 1

#### Swift

```swift
import UIKit
import SafariServices

let BackendAPIBaseURL: String = "" // Set to the URL of your backend server

class ConnectOnboardViewController: UIViewController {

    // ...

    override func viewDidLoad() {
        super.viewDidLoad()

        let connectWithStripeButton = UIButton(type: .system)
        connectWithStripeButton.setTitle("Connect with Stripe", for: .normal)
        connectWithStripeButton.addTarget(self, action: #selector(didSelectConnectWithStripe), for: .touchUpInside)
        view.addSubview(connectWithStripeButton)

        // ...
    }

    @objc
    func didSelectConnectWithStripe() {
        if let url = URL(string: BackendAPIBaseURL)?.appendingPathComponent("onboard-user") {
          var request = URLRequest(url: url)
          request.httpMethod = "POST"
          let task = URLSession.shared.dataTask(with: request) { (data, response, error) in
              guard let data = data,
                  let json = try? JSONSerialization.jsonObject(with: data, options: []) as? [String : Any],
                  let accountURLString = json["url"] as? String,
                  let accountURL = URL(string: accountURLString) else {
                      // handle error
              }

              let safariViewController = SFSafariViewController(url: accountURL)
              safariViewController.delegate = self

              DispatchQueue.main.async {
                  self.present(safariViewController, animated: true, completion: nil)
              }
          }
        }
    }

    // ...
}

extension ConnectOnboardViewController: SFSafariViewControllerDelegate {
    func safariViewControllerDidFinish(_ controller: SFSafariViewController) {
        // the user may have closed the SFSafariViewController instance before a redirect
        // occurred. Sync with your backend to confirm the correct state
    }
}

```

#### Item 2

```xml
<?xml version="1.0" encoding="utf-8"?>
<androidx.constraintlayout.widget.ConstraintLayout
    xmlns:android="http://schemas.android.com/apk/res/android"
    xmlns:app="http://schemas.android.com/apk/res-auto"
    xmlns:tools="http://schemas.android.com/tools"
    android:layout_width="match_parent"
    android:layout_height="match_parent"
    tools:context=".activity.ConnectWithStripeActivity">

    <Button
        android:id="@+id/connect_with_stripe"
        android:text="Connect with Stripe"
        android:layout_height="wrap_content"
        android:layout_width="wrap_content"
        app:layout_constraintBottom_toBottomOf="parent"
        app:layout_constraintEnd_toEndOf="parent"
        app:layout_constraintStart_toStartOf="parent"
        app:layout_constraintTop_toTopOf="parent"
        style="?attr/materialButtonOutlinedStyle"
        />

</androidx.constraintlayout.widget.ConstraintLayout>
```

#### Kotlin

```kotlin
class ConnectWithStripeActivity : AppCompatActivity() {

    private val viewBinding: ActivityConnectWithStripeViewBinding by lazy {
        ActivityConnectWithStripeViewBinding.inflate(layoutInflater)
    }
    private val httpClient = OkHttpClient()

    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        setContentView(viewBinding.root)

        viewBinding.connectWithStripe.setOnClickListener {
            val weakActivity = WeakReference<Activity>(this)
            val request = Request.Builder()
                .url(BACKEND_URL + "onboard-user")
                .post("".toRequestBody())
                .build()
            httpClient.newCall(request)
                .enqueue(object: Callback {
                    override fun onFailure(call: Call, e: IOException) {
                        // Request failed
                    }
                    override fun onResponse(call: Call, response: Response) {
                        if (!response.isSuccessful) {
                            // Request failed
                        } else {
                            val responseData = response.body?.string()
                            val responseJson =
                                responseData?.let { JSONObject(it) } ?: JSONObject()
                            val url = responseJson.getString("url")

                            weakActivity.get()?.let {
                                val builder: CustomTabsIntent.Builder = CustomTabsIntent.Builder()
                                val customTabsIntent = builder.build()
                                customTabsIntent.launchUrl(it, Uri.parse(url))
                            }
                        }
                    }
                })
        }
    }

    internal companion object {
        internal const val BACKEND_URL = "https://example-backend-url.com/"
    }
}
```

#### Item 3

### Gerenciar o usuário que volta à plataforma

O Connect Onboarding exige que você passe tanto um `return_url` quanto um `refresh_url` para lidar com todos os casos em que o usuário da conta é redirecionado para a sua plataforma.

> Você pode usar HTTP para seu `return_url` e para o `refresh_url` enquanto estiver em um ambiente de teste (por exemplo, para testar com o localhost), mas modo de produção aceita apenas HTTPS. Você deve atualizar URLs de teste para URLs HTTPS antes do lançamento.

#### return_url

A Stripe emite um redirecionamento para essa URL quando o usuário da conta conectada conclui o fluxo de onboarding. Isso não significa que todas as informações tenham sido recolhidas ou que não haja requisitos pendentes na conta. Significa apenas que o fluxo foi inserido e encerrado corretamente.

Nenhum estado é transmitido por essa URL. Depois que um usuário for redirecionado para o seu `return_url`, verifique o estado dos requisitos na conta dele fazendo o seguinte:

- Ouça os Webhooks `v2.core.account[requirements].updated`.
- Chame a API [Accounts v2](https://docs.stripe.com/api/v2/core/accounts/retrieve.md) e inspecione o objeto retornado.

#### refresh_url

A Stripe redireciona seu usuário para o `refresh_url` nestes casos:

- O link expirou (alguns minutos se passaram desde a criação do link).
- O usuário já acessou o URL (atualizou a página ou clicou em Voltar ou Avançar no navegador).
- Sua plataforma não consegue mais acessar a conta.
- A conta foi recusada.

Configure sua página `refresh_url` para acionar um método em seu servidor para chamar [Account Links v2](https://docs.stripe.com/api/v2/core/account-links.md) novamente com os mesmos parâmetros e redirecionar o usuário para o novo link.

### Gerenciar usuários que não concluíram o onboarding

Um usuário redirecionado para o seu `return_url` pode não ter concluído o processo de onboarding. Use o endpoint `/v2/core/accounts` para recuperar a conta do usuário e verificar se [configuration.recipient.capabilities.stripe_balance.stripe_transfers.status](https://docs.stripe.com/api/v2/core/accounts/object.md#v2_account_object-configuration-recipient-capabilities-stripe_balance-stripe_transfers-status) está coo `active`. Se o status não estiver `active` e [configuration.destinatário.capabilities.stripe_balance.stripe_transfers.status_details.code](https://docs.stripe.com/api/v2/core/accounts/object.md#v2_account_object-configuration-recipient-capabilities-stripe_balance-stripe_transfers-status_details-code) for `requirements_past_due`, forneça prompts na IU para permitir que o usuário continue o onboarding por meio de um novo link de conta. Para outros códigos, trate-os conforme necessário.

#### Accounts v1

Use a API `/v1/accounts` para [criar](https://docs.stripe.com/api/accounts/create.md) uma conta conectada especificando as [propriedades da conta conectada](https://docs.stripe.com/connect/migrate-to-controller-properties.md) ou o tipo de conta.

```curl
curl https://api.stripe.com/v1/accounts \
  -u "<<YOUR_SECRET_KEY>>:" \
  -d "controller[losses][payments]=application" \
  -d "controller[fees][payer]=application" \
  -d "controller[stripe_dashboard][type]=express"
```

Se você já coletou dados de suas contas conectadas, pode usá-los para preencher o objeto `Account`. Você pode preencher quaisquer dados de conta, inclusive dados pessoais e comerciais, dados de contas externas e muito mais.

Depois de criar uma `Account`, crie uma [Pessoa](https://docs.stripe.com/api/persons/create.md) para representar a pessoa responsável por abrir a conta, com `relationship.representative` definido como verdadeiro e informações da conta que você queira preencher previamente (por exemplo, o nome e sobrenome).

```curl
curl https://api.stripe.com/v1/accounts/{{ACCOUNT_ID}}/persons \
  -u "<<YOUR_SECRET_KEY>>:" \
  -d first_name=Jenny \
  -d last_name=Rosen \
  -d "relationship[representative]=true"
```

O Connect Onboarding não solicita as informações pré-preenchidas. No entanto, ele solicita que o titular da conta confirme as informações pré-preenchidas antes de aceitar o [contrato de serviços do Connect](https://docs.stripe.com/connect/service-agreement-types.md).

Ao testar sua integração, preencha antecipadamente os dados da conta usando [dados de teste](https://docs.stripe.com/connect/testing.md).

### Criar um link da conta

Você pode criar um link de conta chamando a API [Account Links v1](https://docs.stripe.com/api/account_links.md) com os seguintes parâmetros:

- `account`
- `refresh_url`
- `return_url`
- `type` = `account_onboarding`

```curl
curl https://api.stripe.com/v1/account_links \
  -u "<<YOUR_SECRET_KEY>>:" \
  -d "account={{CONNECTEDACCOUNT_ID}}" \
  --data-urlencode "refresh_url=https://example.com/reauth" \
  --data-urlencode "return_url=https://example.com/return" \
  -d type=account_onboarding
```

### Redirecionar o usuário ao URL do link da conta

A resposta da criação do link da conta inclui um valor de `url`. Após autenticar o usuário no seu aplicativo, redirecione-o para esta URL para inseri-lo no fluxo. As URLs de links de conta da [API Account Links v1](https://docs.stripe.com/api/account_links.md) são temporárias e de uso único, pois concedem acesso às informações pessoais do usuário da conta conectada. Autentique o usuário no seu aplicativo antes de redirecioná-lo para esta URL. Se desejar preencher previamente as informações, deverá preencher antes de gerar o link da conta. Depois de criar o link da conta, não será possível ler nem gravar informações da conta conectada.

> Não envie URLs de links de conta por e-mail, SMS ou outra maneira para fora do aplicativo da sua plataforma. Em vez disso, forneça-os ao titular da conta autenticado dentro do seu aplicativo.

#### Item 1

#### Swift

```swift
import UIKit
import SafariServices

let BackendAPIBaseURL: String = "" // Set to the URL of your backend server

class ConnectOnboardViewController: UIViewController {

    // ...

    override func viewDidLoad() {
        super.viewDidLoad()

        let connectWithStripeButton = UIButton(type: .system)
        connectWithStripeButton.setTitle("Connect with Stripe", for: .normal)
        connectWithStripeButton.addTarget(self, action: #selector(didSelectConnectWithStripe), for: .touchUpInside)
        view.addSubview(connectWithStripeButton)

        // ...
    }

    @objc
    func didSelectConnectWithStripe() {
        if let url = URL(string: BackendAPIBaseURL)?.appendingPathComponent("onboard-user") {
          var request = URLRequest(url: url)
          request.httpMethod = "POST"
          let task = URLSession.shared.dataTask(with: request) { (data, response, error) in
              guard let data = data,
                  let json = try? JSONSerialization.jsonObject(with: data, options: []) as? [String : Any],
                  let accountURLString = json["url"] as? String,
                  let accountURL = URL(string: accountURLString) else {
                      // handle error
              }

              let safariViewController = SFSafariViewController(url: accountURL)
              safariViewController.delegate = self

              DispatchQueue.main.async {
                  self.present(safariViewController, animated: true, completion: nil)
              }
          }
        }
    }

    // ...
}

extension ConnectOnboardViewController: SFSafariViewControllerDelegate {
    func safariViewControllerDidFinish(_ controller: SFSafariViewController) {
        // the user may have closed the SFSafariViewController instance before a redirect
        // occurred. Sync with your backend to confirm the correct state
    }
}

```

#### Item 2

```xml
<?xml version="1.0" encoding="utf-8"?>
<androidx.constraintlayout.widget.ConstraintLayout
    xmlns:android="http://schemas.android.com/apk/res/android"
    xmlns:app="http://schemas.android.com/apk/res-auto"
    xmlns:tools="http://schemas.android.com/tools"
    android:layout_width="match_parent"
    android:layout_height="match_parent"
    tools:context=".activity.ConnectWithStripeActivity">

    <Button
        android:id="@+id/connect_with_stripe"
        android:text="Connect with Stripe"
        android:layout_height="wrap_content"
        android:layout_width="wrap_content"
        app:layout_constraintBottom_toBottomOf="parent"
        app:layout_constraintEnd_toEndOf="parent"
        app:layout_constraintStart_toStartOf="parent"
        app:layout_constraintTop_toTopOf="parent"
        style="?attr/materialButtonOutlinedStyle"
        />

</androidx.constraintlayout.widget.ConstraintLayout>
```

#### Kotlin

```kotlin
class ConnectWithStripeActivity : AppCompatActivity() {

    private val viewBinding: ActivityConnectWithStripeViewBinding by lazy {
        ActivityConnectWithStripeViewBinding.inflate(layoutInflater)
    }
    private val httpClient = OkHttpClient()

    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        setContentView(viewBinding.root)

        viewBinding.connectWithStripe.setOnClickListener {
            val weakActivity = WeakReference<Activity>(this)
            val request = Request.Builder()
                .url(BACKEND_URL + "onboard-user")
                .post("".toRequestBody())
                .build()
            httpClient.newCall(request)
                .enqueue(object: Callback {
                    override fun onFailure(call: Call, e: IOException) {
                        // Request failed
                    }
                    override fun onResponse(call: Call, response: Response) {
                        if (!response.isSuccessful) {
                            // Request failed
                        } else {
                            val responseData = response.body?.string()
                            val responseJson =
                                responseData?.let { JSONObject(it) } ?: JSONObject()
                            val url = responseJson.getString("url")

                            weakActivity.get()?.let {
                                val builder: CustomTabsIntent.Builder = CustomTabsIntent.Builder()
                                val customTabsIntent = builder.build()
                                customTabsIntent.launchUrl(it, Uri.parse(url))
                            }
                        }
                    }
                })
        }
    }

    internal companion object {
        internal const val BACKEND_URL = "https://example-backend-url.com/"
    }
}
```

### Gerenciar o usuário que volta à plataforma

O Connect Onboarding exige que você passe um `return_url` e `refresh_url` para gerenciar todos os casos em que o usuário é redirecionado à sua plataforma. É importante implementá-los corretamente para proporcionar a melhor experiência ao usuário.

> Você pode usar HTTP para seu `return_url` e para o `refresh_url` enquanto estiver em um ambiente de teste (por exemplo, para testar com o localhost), mas modo de produção aceita apenas HTTPS. Você deve atualizar URLs de teste para URLs HTTPS antes do lançamento.

#### return_url

A Stripe emite um redirecionamento para essa URL quando o usuário da conta conectada conclui o fluxo de onboarding. Isso não significa que todas as informações tenham sido recolhidas ou que não haja requisitos pendentes na conta. Significa apenas que o fluxo foi inserido e encerrado corretamente.

Nenhum estado é passado por este URL. Após o redirecionamento de um usuário para o `return_url` , verifique o estado do parâmetro `details_submitted` na conta dele realizando uma das seguintes ações:

- Ouça os Webhooks `account.updated`
- Chame a API [Accounts v1](https://docs.stripe.com/api/accounts.md) e inspecione o objeto retornado

#### refresh_url

A Stripe redireciona seu usuário para o `refresh_url` nestes casos:

- O link expirou (alguns minutos se passaram desde a criação do link).
- O usuário já acessou o URL (atualizou a página ou clicou em Voltar ou Avançar no navegador).
- Sua plataforma não consegue mais acessar a conta.
- A conta foi recusada.

Configure sua página `refresh_url` para acionar um método em seu servidor para chamar [Account Links v1](https://docs.stripe.com/api/account_links.md) novamente com os mesmos parâmetros e redirecionar o usuário para o novo link.

### Gerenciar usuários que não concluíram o onboarding

Um usuário que é redirecionado para seu `return_url` pode não ter concluído o processo de onboarding. Use o endpoint `/v1/accounts` para recuperar a conta do usuário e verificar se `charges_enabled`. Se a conta não estiver totalmente integrada, forneça prompts de IU para permitir que o usuário continue fazendo onboarding por meio de um novo link de conta. Você pode determinar se eles concluíram o onboarding verificando o estado do parâmetro `details_submitted` na conta deles.

## Habilitar formas de pagamento

Veja as [configurações de formas de pagamento](https://dashboard.stripe.com/settings/connect/payment_methods) e ative as que pretende aceitar. Pagamentos com cartão, Google Pay e Apple Pay são ativados por padrão, mas você pode ativar e desativar as formas de pagamento conforme a necessidade.

Antes da exibição das formas de pagamento, a Stripe avalia a moeda, as restrições e outros parâmetros dessas formas de pagamento para criar a lista das que são aceitas. Priorizamos as que aumentam a conversão e são mais relevantes para a moeda e a localização do cliente. As formas de pagamento de menor prioridade são ocultas em um menu de estouro.

## Adicionar um endpoint [Lado do servidor]

> #### Nota
> 
> Para exibir o PaymentSheet antes de criar um PaymentIntent, consulte [Colete os dados de pagamento antes de criar um Intent](https://docs.stripe.com/payments/accept-a-payment-deferred.md?type=payment).

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

1. [PaymentIntent](https://docs.stripe.com/api/payment_intents.md): 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.

1. (Opcional) Uma [conta configurada pelo cliente](https://docs.stripe.com/api/v2/core/accounts/object.md#v2_account_object-applied_configurations) ou um objeto [Cliente](https://docs.stripe.com/api/customers.md): para configurar uma forma de pagamento para pagamentos futuros, você deve associá-la a um cliente. Crie um objeto para representar seu cliente quando ele criar uma conta na sua empresa. Se o cliente fizer um pagamento como convidado, você poderá criar um objeto `Conta` ou `Cliente` antes do pagamento e associá-lo à sua própria representação interna da conta do cliente posteriormente.

1. (Opcional) [CustomerSession](https://docs.stripe.com/api/customer_sessions.md): os dados do objeto que representa seu cliente são confidenciais e não podem ser recuperados diretamente de um aplicativo. Uma `CustomerSession` concede ao SDK acesso temporário e restrito à `Conta` ou ao `Cliente` e oferece opções de configuração adicionais. Consulte a lista completa de [opções de configuração](https://docs.stripe.com/api/customer_sessions/create.md#create_customer_session-components).

> Se você nunca salvar cartões para os clientes e não permitir que clientes recorrentes reutilizem cartões salvos, poderá omitir os objetos `Conta` ou `Cliente` e o objeto `CustomerSession` da sua integração.

Por motivos de segurança, o aplicativo não pode criar esses objetos. Para isso, adicione um endpoint ao servidor para:

1. Recupera a `Conta` ou o `Cliente` ou cria um novo.
1. Cria uma [CustomerSession](https://docs.stripe.com/api/customer_sessions.md) para a `Conta` ou o `Cliente`.
1. Cria um `PaymentIntent` com o [valor](https://docs.stripe.com/api/payment_intents/create.md#create_payment_intent-amount), a [moeda](https://docs.stripe.com/api/payment_intents/create.md#create_payment_intent-currency), e a [customer_account](https://docs.stripe.com/api/payment_intents/create.md#create_payment_intent-customer_account) ou o [cliente](https://docs.stripe.com/api/payment_intents/create.md#create_payment_intent-customer).
1. Retorna o *segredo do cliente* (The client secret is a unique key returned from Stripe as part of a PaymentIntent. This key lets the client access important fields from the PaymentIntent (status, amount, currency) while hiding sensitive ones (metadata, customer)) do `PaymentIntent`, o `client_secret` da `CustomerSession`, o ID da `Conta` ou do `Cliente` e sua [chave de publicação](https://dashboard.stripe.com/apikeys) do seu 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.

#### Gerenciar formas de pagamento no Dashboard

Você pode gerenciar formas de pagamento no [Dashboard](https://dashboard.stripe.com/settings/payment_methods). A Stripe processa a devolução de formas de pagamento qualificadas com base em fatores como valor, moeda e fluxo de pagamento da transação. O PaymentIntent é criado usando as formas de pagamento configuradas no Dashboard. Se não quiser usar o Dashboard ou se quiser especificar formas de pagamento manualmente, você pode listá-las usando o atributo `payment_method_types`.

#### curl

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

# Create an CustomerSession for the Customer
curl https://api.stripe.com/v1/customer_sessions \
  -u <<YOUR_SECRET_KEY>>: \
  -X "POST" \
  -d "customer"="{{CUSTOMER_ID}}" \
  -d "components[mobile_payment_element][enabled]"=true \
  -d "components[mobile_payment_element][features][payment_method_save]"=enabled \
  -d "components[mobile_payment_element][features][payment_method_redisplay]"=enabled \
  -d "components[mobile_payment_element][features][payment_method_remove]"=enabled

# Create a PaymentIntent
curl https://api.stripe.com/v1/payment_intents \
  -u <<YOUR_SECRET_KEY>>: \
  -X "POST" \
  -d "customer"="{{CUSTOMER_ID}}" \
  -d "amount"=1099 \
  -d "currency"="eur" \

  -d "automatic_payment_methods[enabled]"=true \
  -d application_fee_amount="123" \
  -d "transfer_data[destination]"="{{CONNECTED_ACCOUNT_ID}}" \
```

#### Listar manualmente as formas de pagamento

#### curl

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

# Create an CustomerSession for the Customer
curl https://api.stripe.com/v1/customer_sessions \
  -u <<YOUR_SECRET_KEY>>: \
  -X "POST" \
  -d "customer"="{{CUSTOMER_ID}}" \
  -d "components[mobile_payment_element][enabled]"=true \
  -d "components[mobile_payment_element][features][payment_method_save]"=enabled \
  -d "components[mobile_payment_element][features][payment_method_redisplay]"=enabled \
  -d "components[mobile_payment_element][features][payment_method_remove]"=enabled

# Create a PaymentIntent
curl https://api.stripe.com/v1/payment_intents \
  -u <<YOUR_SECRET_KEY>>: \
  -X "POST" \
  -d "customer"="{{CUSTOMER_ID}}" \
  -d "amount"=1099 \
  -d "currency"="eur" \
  -d "payment_method_types[]"="bancontact" \
  -d "payment_method_types[]"="card" \
  -d "payment_method_types[]"="ideal" \
  -d "payment_method_types[]"="klarna" \
  -d "payment_method_types[]"="sepa_debit" \
  -d application_fee_amount="123" \
  -d "transfer_data[destination]"="{{CONNECTED_ACCOUNT_ID}}" \
```

> A forma de pagamento precisa aceitar a moeda passada no PaymentIntent. Além disso, sua empresa precisa estar estabelecida em um dos países aceitos pela forma de pagamento. Consulte a página [Opções de integração de formas de pagamento](https://docs.stripe.com/payments/payment-methods/integration-options.md) para obter mais detalhes sobre o que é aceito.

## Integrar a descrição da compra [Lado do cliente]

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`.

#### Accounts v2

```javascript
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_account } = await response.json();

    return {
      paymentIntent,
      ephemeralKey,
      customer_account,
    };
  };

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

    const { error } = await initPaymentSheet({
      merchantDisplayName: "Example, Inc.",
      customerAccountId: customer_account,
      customerEphemeralKeySecret: ephemeralKey,
      paymentIntentClientSecret: paymentIntent,
      // Set `allowsDelayedPaymentMethods` to true if your business accepts 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>
  );
}
```

#### Clientes v1

```javascript

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.

```javascript
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 cliente que está tudo concluído, por exemplo, exibindo uma tela de confirmação do pedido.

Configurar `allowsDelayedPaymentMethods` como verdadeiro permite formas de pagamento de [notificação assíncrona](https://docs.stripe.com/payments/payment-methods.md#payment-notification) 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.

## Configurar um URL de retorno (somente iOS) [Lado do cliente]

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](https://developer.apple.com/documentation/xcode/defining-a-custom-url-scheme-for-your-app) e configure seu aplicativo delegado para encaminhar o URL ao SDK. A Stripe não aceita [links universais](https://developer.apple.com/documentation/xcode/allowing-apps-and-websites-to-link-to-your-content).

#### SceneDelegate

#### Swift

```swift
// 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
    }
}

```

#### AppDelegate

#### Swift

```swift
// This method handles opening custom URL schemes (for example, "your-app://stripe-redirect")
func application(_ app: UIApplication, open url: URL, options: [UIApplication.OpenURLOptionsKey: Any] = [:]) -> Bool {
    let stripeHandled = StripeAPI.handleURLCallback(with: url)
    if (stripeHandled) {
        return true
    } else {
        // This was not a Stripe url – handle the URL normally as you would
    }
    return false
}
```

#### SwiftUI

#### Swift

```swift

@main
struct MyApp: App {
  var body: some Scene {
    WindowGroup {
      Text("Hello, world!").onOpenURL { incomingURL in
          let stripeHandled = StripeAPI.handleURLCallback(with: incomingURL)
          if (!stripeHandled) {
            // This was not a Stripe url – handle the URL normally as you would
          }
        }
    }
  }
}
```

Além disso, defina o [returnURL](https://stripe.dev/stripe-ios/stripe-paymentsheet/Classes/PaymentSheet/Configuration.html#/s:6Stripe12PaymentSheetC13ConfigurationV9returnURLSSSgvp) no seu objeto [PaymentSheet.Configuration](https://stripe.dev/stripe-ios/stripe-paymentsheet/Classes/PaymentSheet/Configuration.html) para o URL do seu aplicativo.

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

## Gerenciar eventos pós-pagamento

Stripe envia um evento [payment_intent.succeeded](https://docs.stripe.com/api/events/types.md#event_types-payment_intent.succeeded) quando o pagamento é concluído. Use a [ferramenta Dashboard webhook](https://dashboard.stripe.com/webhooks) ou siga o [guia de webhooks](https://docs.stripe.com/webhooks/quickstart.md) 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](https://stripe.com/payments/payment-methods-guide) 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:

| Evento                                                                                                                          | Descrição                                                                                                                                                                                                                                                                     | Ação                                                                                                                                                                                            |
| ------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [payment_intent.succeeded](https://docs.stripe.com/api/events/types.md?lang=php#event_types-payment_intent.succeeded)           | Enviado quando um cliente conclui um pagamento com êxito.                                                                                                                                                                                                                     | Envie ao cliente uma confirmação de pedido e *processe* (Fulfillment is the process of providing the goods or services purchased by a customer, typically after payment is collected) o pedido. |
| [payment_intent.processing](https://docs.stripe.com/api/events/types.md?lang=php#event_types-payment_intent.processing)         | Enviado quando um cliente inicia um pagamento, mas o pagamento ainda precisa ser concluído. Esse evento costuma ser enviado quando um cliente inicia um débito bancário. Ele é seguido por um evento `payment_intent.succeeded` ou `payment_intent.payment_failed` no futuro. | Envie ao cliente uma confirmação do pedido que indica que o pagamento está pendente. Para produtos digitais, pode ser necessário executar o pedido antes de aguardar a conclusão do pagamento.  |
| [payment_intent.payment_failed](https://docs.stripe.com/api/events/types.md?lang=php#event_types-payment_intent.payment_failed) | Enviado quando um cliente tenta fazer um pagamento, mas o pagamento falha.                                                                                                                                                                                                    | Se um pagamento passa de `processing` para `payment_failed`, ofereça ao cliente outra tentativa para pagar.                                                                                     |

## Testar a integração

#### Cartões

| Número do cartão    | Cenário                                                                                                                                                                                                                                                                                             | Como testar                                                                                                                 |
| ------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------- |
| 4242424242424242    | O pagamento com cartão é bem-sucedido e não precisa de autenticação.                                                                                                                                                                                                                                | Preencha o formulário do cartão de crédito usando o número do cartão de crédito com qualquer validade, CVC e código postal. |
| 4000002500003155    | O pagamento com cartão precisa de *autenticação* (Strong Customer Authentication (SCA) is a regulatory requirement in effect as of September 14, 2019, that impacts many European online payments. It requires customers to use two-factor authentication like 3D Secure to verify their purchase). | Preencha o formulário do cartão de crédito usando o número do cartão de crédito com qualquer validade, CVC e código postal. |
| 4000000000009995    | O cartão é recusado com um código de recusa como `insufficient_funds`.                                                                                                                                                                                                                              | Preencha o formulário do cartão de crédito usando o número do cartão de crédito com qualquer validade, CVC e código postal. |
| 6205500000000000004 | O cartão UnionPay tem um comprimento variável de 13 a 19 dígitos.                                                                                                                                                                                                                                   | Preencha o formulário do cartão de crédito usando o número do cartão de crédito com qualquer validade, CVC e código postal. |

#### Débito bancário autenticado

| Forma de pagamento | Cenário                                                                                                                                                                                                | Como testar                                                                                                                                                                                                |
| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Bancontact, iDEAL  | Seu cliente não faz a autenticação na página de redirecionamento de uma forma de pagamento baseada em redirecionamento e notificação imediata.                                                         | Escolha qualquer forma de pagamento baseada em redirecionamento, preencha os dados obrigatórios e confirme o pagamento. Em seguida, clique em **Falhar pagamento de teste** na página de redirecionamento. |
| Pay by Bank        | O cliente paga com uma forma de pagamento baseada em redirecionamento e [notificação posterior](https://docs.stripe.com/payments/payment-methods.md#payment-notification).                             | Escolha a forma de pagamento, preencha os dados obrigatórios e confirme o pagamento. Em seguida, clique em **Concluir o pagamento de teste** na página de redirecionamento.                                |
| Pay by Bank        | Seu cliente não faz a autenticação na página de redirecionamento de uma forma de pagamento baseada em redirecionamento e notificação posterior.                                                        | Escolha a forma de pagamento, preencha os dados obrigatórios e confirme o pagamento. Em seguida, clique em **Falhar o pagamento de teste** na página de redirecionamento.                                  |
| BLIK               | Os pagamentos BLIK falham de várias formas: falhas imediatas (por exemplo, o código está vencido ou inválido), erros atrasados (o banco recusa) ou limites de tempo (o cliente não respondeu a tempo). | Use padrões de e-mail para [simular as diferentes falhas.](https://docs.stripe.com/payments/blik/accept-a-payment.md#simulate-failures)                                                                    |

#### Débitos bancários

| Forma de pagamento     | Cenário                                                                                           | Como testar                                                                                                                                                                     |
| ---------------------- | ------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Débito automático SEPA | O cliente paga com débito automático SEPA.                                                        | Preencha o formulário usando o número de conta `AT321904300235473204`. Inicialmente, o status do PaymentIntent muda para processando e, três minutos depois, para bem-sucedido. |
| Débito automático SEPA | O status da intenção de pagamento do cliente muda de `processing` para `requires_payment_method`. | Preencha o formulário usando o número de conta `AT861904300235473202`.                                                                                                          |

Consulte [Testes](https://docs.stripe.com/testing.md) para obter mais informações sobre como testar sua integração.

## Optional: Habilitar Apple Pay

### Solicitar um ID de comerciante da Apple

Obtenha um ID de comerciante da Apple [solicitando um novo identificador](https://developer.apple.com/account/resources/identifiers/add/merchant) no site de desenvolvedores da Apple.

Preencha o formulário com descrição e identificador. A descrição é para seu controle e pode ser modificada no futuro. A Stripe recomenda que você use o nome do aplicativo como identificador (por exemplo, `merchant.com.{{YOUR_APP_NAME}}`).

### Criar um certificado do Apple Pay

Crie um certificado para criptografia de dados de pagamento pelo aplicativo.

Vá até [Configurações de certificado do iOS](https://dashboard.stripe.com/settings/ios_certificates) no Dashboard, clique em **Adicionar novo aplicativo** e siga o guia.

Baixe um arquivo de solicitação de assinatura de certificado (CSR) para obter um certificado seguro da Apple que permite usar o Apple Pay.

Um arquivo CSR deve ser usado para emitir exatamente um certificado. Se você trocar seu ID de comerciante da Apple, acesse as [Configurações de certificado do iOS](https://dashboard.stripe.com/settings/ios_certificates) no Dashboard para obter um novo CSR e certificado.

### Integrar com Xcode

Adicione as funções do Apple Pay ao aplicativo. No Xcode, abra as configurações do projeto, clique na guia **Signing & Capabilities** e adicione o recurso **Apple Pay**. Talvez seja necessário fazer login na sua conta de desenvolvedor. Selecione o ID de comerciante criado anteriormente e o aplicativo já pode aceitar Apple Pay.
![](https://b.stripecdn.com/docs-statics-srv/assets/xcode.a701d4c1922d19985e9c614a6f105bf1.png)

Habilitar o recurso Apple Pay no Xcode

### Adicionar Apple Pay

#### Pagamento avulso

Passe seu ID de comerciante quando criar `StripeProvider`:

```javascript
import { StripeProvider } from '@stripe/stripe-react-native';

function App() {
  return (
    <StripeProvider
      publishableKey="<<YOUR_PUBLISHABLE_KEY>>"
      merchantIdentifier="MERCHANT_ID"
    >
      {/* Your app code here */}
    </StripeProvider>
  );
}
```

Quando você chamar `initPaymentSheet`, passe seus [ApplePayParams](https://stripe.dev/stripe-react-native/api-reference/modules/PaymentSheet.html#ApplePayParams):

```javascript
await initPaymentSheet({
  // ...
  applePay: {
    merchantCountryCode: 'US',
  },
});
```

#### Pagamentos recorrentes

Quando você chamar `initPaymentSheet`, passe um [ApplePayParams](https://stripe.dev/stripe-react-native/api-reference/modules/PaymentSheet.html#ApplePayParams) com `merchantCountryCode` definido como o código de país da sua empresa.

De acordo com as [diretrizes da Apple](https://developer.apple.com/design/human-interface-guidelines/apple-pay#Supporting-subscriptions) para pagamentos recorrentes, você também deve definir um `cardItems` que inclua um [RecurringCartSummaryItem](https://stripe.dev/stripe-react-native/api-reference/modules/ApplePay.html#RecurringCartSummaryItem) com o valor que pretende cobrar (por exemplo, “59,95 USD por mês”).

Você também pode adotar [tokens de comerciante](https://developer.apple.com/apple-pay/merchant-tokens/) definindo a `request` com seu `type` definido como `PaymentRequestType.Recurring`

Para saber como usar pagamentos recorrentes com Apple Pay, consulte a [documentação do PassKit da Apple](https://developer.apple.com/documentation/passkit/pkpaymentrequest).

#### iOS (React Native)

```javascript
const initializePaymentSheet = async () => {
  const recurringSummaryItem = {
    label: 'My Subscription',
    amount: '59.99',
    paymentType: 'Recurring',
    intervalCount: 1,
    intervalUnit: 'month',
    // Payment starts today
    startDate: new Date().getTime() / 1000,

    // Payment ends in one year
    endDate: new Date().getTime() / 1000 + 60 * 60 * 24 * 365,
  };

  const {error} = await initPaymentSheet({
    // ...
    applePay: {
      merchantCountryCode: 'US',
      cartItems: [recurringSummaryItem],
      request: {
        type: PaymentRequestType.Recurring,
        description: 'Recurring',
        managementUrl: 'https://my-backend.example.com/customer-portal',
        billing: recurringSummaryItem,
        billingAgreement:
          "You'll be billed $59.99 every month for the next 12 months. To cancel at any time, go to Account and click 'Cancel Membership.'",
      },
    },
  });
};
```

### Rastreamento de pedidos

Para adicionar informações de [rastreamento de pedido](https://developer.apple.com/design/human-interface-guidelines/technologies/wallet/designing-order-tracking) no iOS 16 ou mais recente, configure uma função de retorno de chamada `setOrderTracking`. A Stripe chama sua implementação após a conclusão do pagamento, mas antes que o iOS ignore a descrição de compra do Apple Pay.

Na implementação da função de retorno de chamada `setOrderTracking`, obtenha os detalhes do pedido concluído no seu servidor e passe esses dados à função de `completion` informada.

Para saber mais sobre rastreamento de pedidos, consulte a [documentação de pedidos da carteira da Apple](https://developer.apple.com/documentation/walletorders).

#### iOS (React Native)

```javascript
await initPaymentSheet({
  // ...
  applePay: {
    // ...
    setOrderTracking: async complete => {
      const apiEndpoint =
        Platform.OS === 'ios'
          ? 'http://localhost:4242'
          : 'http://10.0.2.2:4567';
      const response = await fetch(
        `${apiEndpoint}/retrieve-order?orderId=${orderId}`,
        {
          method: 'GET',
          headers: {
            'Content-Type': 'application/json',
          },
        },
      );
      if (response.status === 200) {
        const orderDetails = await response.json();
        // orderDetails should include orderIdentifier, orderTypeIdentifier,
        // authenticationToken and webServiceUrl
        complete(orderDetails);
      }
    },
  },
});
```

## Optional: Habilitar Google Pay

### Configure a integração

Para usar o Google Pay, habilite a API Google Pay adicionando o seguinte à `<application>` tag do seu **AndroidManifest.xml**:

```xml
<application>
  ...
  <meta-data
    android:name="com.google.android.gms.wallet.api.enabled"
    android:value="true" />
</application>
```

Veja mais detalhes na [Configuração da API Google Pay](https://developers.google.com/pay/api/android/guides/setup) do Google Pay para Android.

### Adicionar Google Pay

Quando você inicializar `PaymentSheet`, defina `merchantCountryCode` como o código de país da sua empresa e defina `googlePay` como true.

Você também pode usar o ambiente de teste passando o parâmetro `testEnv`. Você só pode testar o Google Pay em um dispositivo Android físico. Siga a [documentação do React Native](https://reactnative.dev/docs/running-on-device) para testar seu aplicativo em um dispositivo físico.

```javascript
const { error, paymentOption } = await initPaymentSheet({
  // ...
  googlePay: {
    merchantCountryCode: 'US',
    testEnv: true, // use test environment
  },
});
```

## Habilitar leitura de cartões [Lado do cliente]

> Ativar a leitura de cartões é obrigatório para o processo de análise de aplicativos da Apple no iOS. No Android, a leitura de cartões não é obrigatória, mas recomendamos que seja habilitada.

### iOS​

Para habilitar o suporte à leitura de cartões no iOS, defina `NSCameraUsageDescription` (**Privacy - Camera Usage Description**) no `Info.plist` do seu aplicativo e informe um motivo para o acesso à câmera (por exemplo, “Para ler cartões”).

### Android

To enable card scanning support, [request production access](https://developers.google.com/pay/api/android/guides/test-and-deploy/request-prod-access) to the Google Pay API from the [Google Pay and Wallet Console](https://pay.google.com/business/console?utm_source=devsite&utm_medium=devsite&utm_campaign=devsite).

- Se você ativou o Google Pay, o recurso de escaneamento de cartões está automaticamente disponível em nossa IU em dispositivos elegíveis. Para saber mais sobre dispositivos elegíveis, consulte as [restrições da API do Google Pay](https://developers.google.com/pay/payment-card-recognition/debit-credit-card-recognition)
- **Importante:** O recurso de escanear cartão só aparece em builds assinadas com a mesma chave de assinatura registrada no [Google Pay & Wallet Console](https://pay.google.com/business/console). Builds de teste ou debug usando chaves de assinatura diferentes (por exemplo, builds distribuídas pelo Firebase App Tester) não mostrarão a opção **Escanear cartão**. Para testar o escaneamento de cartão em versões pré-lançamento, você deve:
  - Assinar suas builds de teste com a chave de assinatura de produção
  - Adicionar sua impressão digital da chave de assinatura de teste ao Google Pay e Wallet Console

## Optional: Personalizar a descrição

Toda personalização é configurada usando `initPaymentSheet`.

### Aparência

Personalize as cores, fontes e outros elementos para combinar com a aparência do seu app usando a [API de aparência](https://docs.stripe.com/elements/appearance-api/mobile.md?platform=react-native).

### Nome de exibição do comerciante

Especifique o nome da empresa exibido para o cliente definindo `merchantDisplayName`. Por padrão, este é o nome do seu aplicativo.

```javascript
await initPaymentSheet({
  // ...
  merchantDisplayName: 'Example Inc.',
});
```

### Modo escuro

Por padrão, o `PaymentSheet` se adapta automaticamente às configurações de aparência do sistema do usuário (modo claro e escuro). É possível alterar isso configurando a propriedade `style` como modo `alwaysLight` ou `alwaysDark` no iOS.

```javascript
await initPaymentSheet({
  // ...
  style: 'alwaysDark',
});
```

No Android, configure o modo claro ou escuro no seu aplicativo:

```
// force dark
AppCompatDelegate.setDefaultNightMode(AppCompatDelegate.MODE_NIGHT_YES)
// force light
AppCompatDelegate.setDefaultNightMode(AppCompatDelegate.MODE_NIGHT_NO)
```

### Dados de faturamento padrão

Para definir valores padrão para dados de cobrança coletados no PaymentSheet, configure a propriedade `defaultBillingDetails`. A `PaymentSheet` preenche previamente seus campos com os valores que você informou.

```javascript
await initPaymentSheet({
  // ...
  defaultBillingDetails: {
      email: 'foo@bar.com',
      address: {
        country: 'US',
      },
  },
});
```

### Coletar dados de cobrança

Use `billingDetailsCollectionConfiguration` para especificar como você deseja coletar dados de cobrança no PaymentSheet.

Você pode coletar o nome, e-mail, número de telefone e endereço do cliente.

Se não pretende coletar os valores exigidos pela forma de pagamento, faça o seguinte:

1. Anexe os valores não coletados por `PaymentSheet` à propriedade `defaultBillingDetails`.
1. Defina `billingDetailsCollectionConfiguration.attachDefaultsToPaymentMethod` como `true`.

```javascript
await initPaymentSheet({
  // ...
  defaultBillingDetails: {
    email: 'foo@bar.com',
  },
  billingDetailsCollectionConfiguration: {
    name: PaymentSheet.CollectionMode.ALWAYS,
    email: PaymentSheet.CollectionMode.NEVER,
    address: PaymentSheet.AddressCollectionMode.FULL,
    attachDefaultsToPaymentMethod: true
  },
});
```

> Consulte seu jurídico sobre as leis que se aplicam à coleta de dados. Só colete números de telefone se precisar deles para a transação.

## Optional: Conclua o pagamento em sua IU

Você pode exibir a Payment Sheet apenas para coletar dados da forma de pagamento e depois chamar um método `confirm` para concluir o pagamento na IU do aplicativo. Isso é útil quando você tem um botão de compra personalizado ou precisa de mais etapas após a coleta dos dados do pagamento.
![](https://b.stripecdn.com/docs-statics-srv/assets/react-native-multi-step.84d8a0a44b1baa596bda491322b6d9fd.png)

> Um exemplo de integração está [disponível no GitHub](https://github.com/stripe/stripe-react-native/blob/master/example/src/screens/PaymentsUICustomScreen.tsx).

1. Primeiro, chame `initPaymentSheet` e passe `customFlow: true`. `initPaymentSheet` é resolvido com uma opção de pagamento inicial que contém uma imagem e um rótulo representando a forma de pagamento do cliente. Atualize a IU com esses dados.

```javascript
const {
  initPaymentSheet,
  presentPaymentSheet,
  confirmPaymentSheetPayment,
} = useStripe()

const { error, paymentOption } = await initPaymentSheet({
  customerId: customer,
  customerEphemeralKeySecret: ephemeralKey,
  paymentIntentClientSecret: paymentIntent,
  customFlow: true,
  merchantDisplayName: 'Example Inc.',
});
// Update your UI with paymentOption
```

1. Use `presentPaymentSheet` para coletar detalhes de pagamento. Quando o cliente termina, a folha se desfaz por si mesma e resolve a promessa. Atualize sua IU com os detalhes da forma de pagamento selecionada.

```javascript
const { error, paymentOption } = await presentPaymentSheet();
```

1. Use `confirmPaymentSheetPayment` para confirmar o pagamento. Isso é resolvido com o resultado do pagamento.

```javascript
const { error } = await confirmPaymentSheetPayment();

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

Configurar `allowsDelayedPaymentMethods` como verdadeiro permite formas de pagamento de [notificação assíncrona](https://docs.stripe.com/payments/payment-methods.md#payment-notification) 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.


# Sem código

> This is a Sem código for when platform is no-code. View the full page at https://docs.stripe.com/connect/end-to-end-marketplace?platform=no-code.

Este guia demonstra como aceitar pagamentos de clientes e mover fundos para as contas bancárias dos seus vendedores ou prestadores de serviços, sem precisar saber programar. Use este guia se você:

- Deseja aceitar pagamentos de clientes e fazer repasses a vendedores ou prestadores de serviços sem programação.
- Deseja testar rapidamente a adequação ao mercado de um produto sem programação.
- É um marketplace que vende diretamente a clientes finais (ao contrário de uma plataforma SaaS que vende software para ajudar outras pessoas a operar seus próprios negócios).

Neste exemplo, criaremos um marketplace que permite que artistas de camisetas vendam camisetas personalizadas. Você também pode usar os conceitos abordados neste guia em outras aplicações comerciais.

## Pré-requisitos

1. [Cadastre sua plataforma](https://dashboard.stripe.com/connect).
1. [Verifique e adicione os dados da empresa no Dashboard](https://dashboard.stripe.com/account/onboarding).
1. Finalize seu [perfil da plataforma](https://dashboard.stripe.com/connect/settings/profile).
1. Personalize suas configurações de marca do Connect na [página de configurações do Stripe Dashboard](https://dashboard.stripe.com/settings/connect/stripe-dashboard/branding) e personalize suas configurações de marca de pagamento Link na [página de configurações de marca](https://dashboard.stripe.com/settings/branding) de do Checkout.

## Criar uma conta conectada

Quando um vendedor ou prestador de serviços se registra no seu marketplace, é preciso criar uma conta de usuário (chama de *connected account*) para transferir fundos para a conta bancária deles. Contas conectadas representam seus vendedores ou prestadores de serviços. No nosso exemplo de marketplace de camisetas, a conta conectada representa o artista que faz as camisetas.

### Crie um link de onboarding de conta conectada

#### Accounts v2

- Acesse a página [Contas conectadas](https://dashboard.stripe.com/connect/accounts) e clique em **+Criar** para criar uma conta conectada.
- Selecione **Comerciante** e clique em **Próximo**
- Clique em **Editar** para **Propriedades da conta**
- Selecione **Express** para **Acesso ao Dashboard da Stripe** e clique em **Salvar**
- Clique em **Criar** para criar a conta e gerar um link para fazer onboarding que você poderá compartilhar com seu vendedor ou provedor de serviços por e-mail, SMS ou outros meios privados. Não compartilhe esse link publicamente.
![O modal de criação de conta exibindo um link do Express gerado para onboarding de uma conta conectada](https://b.stripecdn.com/docs-statics-srv/assets/no-code-connect-v2-express-link.9b4b6bc618d0ecab2b0f2a146f600915.png)

Criar um link de onboarding

#### Accounts v1

- Acesse a página [Contas conectadas](https://dashboard.stripe.com/connect/accounts) e clique em **+Criar** para criar uma conta conectada.
- Selecione **Express** para o tipo de conta e selecione o país onde essa conta conectada está localizada. A Stripe permite que plataformas em países aceitos [criem contas conectadas em outros países aceitos pela Stripe](https://docs.stripe.com/connect/express-accounts.md#onboarding-express-accounts-outside-of-your-platforms-country).
- Clique em **Continuar** para gerar o link de onboarding que pode compartilhar com seu vendedor ou prestador de serviços por e-mail, SMS ou outros meios privados. Não o compartilhe publicamente.
![O modal de criação de conta exibindo um link do Express gerado para onboarding de uma conta conectada](https://b.stripecdn.com/docs-statics-srv/assets/no-code-connect-v1-express-link.0ce2e3df98419aae23f88c5cb77ca3f4.png)

Criar um link de onboarding

Este link encaminha vendedores e prestadores de serviços para um formulário de cadastro, onde fornecem dados de identificação e bancários para fazer o onboarding na sua marketplace. No nosso exemplo de um marketplace de camisetas, compartilhe este link com o artista de camisetas para fazer o onboarding. Este link expira após 90 dias e é para uso por um único vendedor ou prestador de serviços. Após o onboarding, você pode ver os detalhes da sua conta na sua página [Contas conectadas](https://dashboard.stripe.com/connect/accounts). Repita essas instruções sempre que precisar adicionar novos vendedores ou prestadores de serviços.
![Uma única conta é exibida na exibição em lista de contas conectadas](https://b.stripecdn.com/docs-statics-srv/assets/no-code-connect-connected-accounts.a62a6dc14ef6c95ae5a1e36801090945.png)

## Criar o Payment Link para aceitar pagamentos

Agora que você criou uma conta conectada, crie um link de pagamento para aceitar pagamentos dos seus clientes, sem precisar de programação. Quando você enviar esse link para o cliente do seu marketplace, ele será direcionado para uma página hospedada pela Stripe, onde poderá efetuar o pagamento. No exemplo do marketplace de camisetas, os clientes compram camisetas pelo seu marketplace e você paga aos artistas que criam e produzem as camisetas. Para configurar isso, clique em **+Create link** (+Criar link) na [página Payment Links](https://dashboard.stripe.com/payment-links) e siga as instruções.

### Etapa 2.1: Adicione o produto

Você configura os links de pagamento para um produto e preço específicos, então o primeiro passo é [adicionar o produto](https://support.stripe.com/questions/how-to-create-products-and-prices) que deseja vender. Clique em **+Add new product** (+Adicionar novo produto) para adicionar um produto.
![A primeira página do formulário de criação do link de pagamento](https://b.stripecdn.com/docs-statics-srv/assets/no-code-connect-empty-payment-link.9885cf82263d39d2be55c4fbdcbcbb9f.png)

Defina o nome, a descrição e o preço do seu produto, que ficam visíveis para o cliente na página de Checkout para onde ele é redirecionado. Após inserir as informações do novo produto, clique em **+Adicionar produto** para adicioná-lo. Neste exemplo, estamos adicionando um produto de camiseta de tamanho médio, por isso, configure o Payment Link para esse produto específico. se também quisermos vender camisetas pequenas ou com outros designs, precisamos seguir as instruções acima para criar um novo Payment Link e um novo produto.
![O modal de criação de produto encontrado no formulário de criação do link de pagamento](https://b.stripecdn.com/docs-statics-srv/assets/no-code-connect-create-product.ce265a710c21ecb80ac7715dc240721a.png)

### Etapa 2.2: Personalize o Payment Link

Personalize o Payment Link para que os clientes usem códigos promocionais, ajustem a quantidade do produto ou insiram endereços de entrega e cobrança. No nosso exemplo de um marketplace de camisetas, o cliente precisa poder comprar o número de camisetas desejado. Também é preciso obter o endereço de entrega para enviar as camisetas. Para habilitar essas opções, selecione **Permitir que os clientes ajustem a quantidade** e **Coletar endereços dos clientes** e clique em **Avançar**.

### Etapa 2.3: Decida quando pagar sua conta conectada

Você tem duas opções para fazer repasses à sua conta conectada.

- Se já souber qual conta conectada será paga com o valor obtido por este Payment Link, faça o repasse automaticamente.
- Mas se não souber com antecedência qual é a conta conectada ou se precisar pagar várias contas conectadas, faça o repasse mais tarde.

#### Fazer repasse automaticamente

#### Selecionar a conta conectada para pagar

Marque a caixa de seleção **Dividir o pagamento com uma conta conectada**. Esta caixa de seleção permite que uma conta conectada seja paga automaticamente quando um cliente compra o produto deste Payment Link. No nosso exemplo, queremos pagar automaticamente Jamie, o artista da camiseta, sempre que um cliente comprar a camiseta. Para fazer isso, especificamos Jamie como a conta conectada.

#### Especificar a tarifa da plataforma

Para manter uma parte do pagamento do seu marketplace, especifique uma tarifa da plataforma, que é um valor fixo por pagamento com este link de pagamento e não muda com base em quantidade, descontos ou impostos. O limite máximo é o valor total da compra. No exemplo, nosso marketplace de camisetas coleta uma tarifa de plataforma de US$&nbsp;1 por venda e envia o restante do pagamento (US$&nbsp;9) ao artista de camisetas. Se o cliente comprar duas camisetas, usar um código promocional ou precisar pagar mais impostos sobre a compra de US$&nbsp;10, o marketplace de camisetas continuará recebendo a tarifa de plataforma de US$&nbsp;1 por venda. Para produtos com pagamentos recorrentes (assinaturas), você pode especificar uma tarifa de plataforma como uma porcentagem do valor total da transação.
![A segunda página do formulário de criação do link de pagamento. Esta página inclui opções para direcionar fundos para contas conectadas.](https://b.stripecdn.com/docs-statics-srv/assets/no-code-connect-create-payment-link-page-2.465b89cd12b53c1e3e623a0a3b03ffb0.png)

Após configurar o Payment Link para dividir o pagamento com sua conta conectada, clique em **+Criar link** para gerar o URL do Payment Link.

Após o cliente fazer o pagamento, a Stripe transfere o valor total do saldo pendente da conta e depois transfere o valor da tarifa da plataforma para a conta da plataforma como receita para facilitar a venda. Em seguida, a Stripe deduz as tarifas da Stripe da tarifa de plataforma. Nos bastidores, esse fluxo de fundos é chamado de [cobrança de destino](https://docs.stripe.com/connect/destination-charges.md).

#### Fazer o repasse mais tarde

#### Pague sua conta conectada mais tarde

Em alguns casos, você pode preferir transferir fundos manualmente para uma conta conectada em um momento posterior, em vez de automaticamente no momento da compra. Isso pode acontecer se você ainda não souber qual conta conectada deve receber os fundos ou se precisar pagar várias contas conectadas por uma única venda. Por exemplo:

- Você vende uma camiseta que é fruto de colaboração entre dois artistas, e cada um deve receber metade do valor.
- Você vende uma camiseta que pode ser feita por um de vários artistas e ainda não sabe qual deles processará o pedido.

Para criar o Payment Link para aceitar pagamentos de clientes, *não* marque **Dividir o pagamento com uma conta conectada** e depois clique em **Criar link** para gerar seu Payment Link. Quando estiver pronto para pagar sua conta conectada, acesse a seção **Saldo** da página de detalhes da conta conectada e clique em **Enviar fundos**. Nos bastidores, esse fluxo de fundos é chamado de [Separar cobrança e transferência](https://docs.stripe.com/connect/separate-charges-and-transfers.md).

## Compartilhe o Payment Link com seus clientes

Agora que você criou seu Payment Link, copie o URL do Payment Link e compartilhe-o no seu site ou por mídias sociais. Quando um cliente clicar no URL do seu Payment Link, ele verá sua página de Checkout personalizada (exemplo abaixo) e poderá inserir os dados de pagamento — é possível pagar usando um celular ou computador com um cartão, Apple Pay ou Google Pay.
![](https://d37ugbyn3rpeym.cloudfront.net/docs/connect/video/no-code-connect-mobile-payment-link.mp4)
## Após o pagamento

### Etapa 4.1: Veja seus pagamentos

Vá até a [página de pagamentos](https://dashboard.stripe.com/payments) para ver a lista de pagamentos que sua empresa aceitou. Você pode clicar em um pagamento específico para ver mais detalhes, como o endereço de entrega, caso tenha optado por coletar o produto. Você pode ver as [tarifas de inscrição](https://dashboard.stripe.com/connect/application_fees) que sua empresa cobrou em cada pagamento ou acessar a [página de saldo](https://dashboard.stripe.com/balance/overview) para ver o total de fundos disponíveis.

### Etapa 4.2: Execução

Após a conclusão do pagamento, é preciso gerenciar a *execução* (Fulfillment is the process of providing the goods or services purchased by a customer, typically after payment is collected) do produto. No exemplo do marketplace de camisetas, é preciso também enviar as camisetas ao comprador após o pagamento.

## Optional: Adicionar formas de pagamento

O Payment Links aceita [mais de 20 formas de pagamento](https://docs.stripe.com/payments/payment-methods/payment-method-support.md#product-support). Você pode habilitá-las nas [configurações de formas de pagamento](https://dashboard.stripe.com/settings/payment_methods). Depois de habilitadas, a Stripe mostra dinamicamente as formas de pagamento com mais probabilidade de aumentar a conversão e maior adequação para a moeda e a localização do cliente.

> A Stripe passou a aceitar mais formas de pagamento em 25 de janeiro de 2022. Os links de pagamento criados antes dessa data aceitam apenas pagamentos com cartões e carteiras. Crie outro link para habilitar mais formas de pagamento.

Algumas formas de pagamento, como débitos bancários ou guias, demoram até 14 dias para confirmar o pagamento. Use webhooks para receber uma notificação quando o pagamento for finalizado e iniciar a execução. Consulte o nosso [guia de execução](https://docs.stripe.com/checkout/fulfillment.md#create-payment-event-handler).


## Contestações

Como [comerciante de liquidação](https://docs.stripe.com/connect/destination-charges.md#settlement-merchant) das cobranças, sua plataforma é responsável pelas contestações. Leia com atenção as [práticas recomendadas](https://docs.stripe.com/disputes/responding.md) para responder a contestações.

## Repasses

Por padrão, todos os fundos transferidos para uma conta conectada são acumulados no [saldo Stripe](https://docs.stripe.com/connect/account-balances.md) da conta conectada e repassados diariamente. É possível alterar a frequência dos *repasses* (A payout is the transfer of funds to an external account, usually a bank account, in the form of a deposit) na página de detalhes da conta conectada, clicando no botão mais à direita da seção **Saldo**, e selecionando **Editar cronograma de repasses**.

## Reembolsos

Para emitir reembolsos, vá até a página [Pagamentos](https://dashboard.stripe.com/payments). Selecione pagamentos individuais clicando na caixa de seleção à esquerda de qualquer pagamento que você quiser reembolsar. Após selecionar um pagamento, a Stripe exibe um botão **Reembolsar** no canto superior direito da página. Clique no botão **Reembolsar** para emitir um reembolso para clientes para todos os pagamentos que você selecionou.

> Por padrão, contas conectadas não podem iniciar reembolsos diretamente a partir do [Express Dashboard](https://docs.stripe.com/connect/express-dashboard.md). Se suas contas conectadas estiverem usando o Express Dashboard, você pode processar os reembolsos em nome delas ou permitir que realizem os próprios reembolsos ajustando as [funcionalidades do Express Dashboard](https://docs.stripe.com/connect/express-dashboard.md#express-dashboard-features).

## See also

- [Gerenciar contas conectadas no Dashboard](https://docs.stripe.com/connect/dashboard.md)
- [Emitir reembolsos](https://docs.stripe.com/connect/direct-charges.md#issue-refunds)
- [Personalizar descrições no extrato](https://docs.stripe.com/connect/statement-descriptors.md)
- [Trabalhar com várias moedas](https://docs.stripe.com/connect/currencies.md)
- [Express dashboard](https://docs.stripe.com/connect/express-dashboard.md)