Criar um marketplace

Use a API /v2/core/accounts para criar uma conta conectada, especificando o dashboard da conta conectada e as responsabilidades.

curl -X POST https://api.stripe.com/v2/core/accounts \
  -H "Authorization: Bearer 
sk_test_BQokikJOvBiI2HlWgH4olfQ2
" \
  -H "Stripe-Version: 2025-08-27.preview" \
  --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.

Depois de criar uma Conta, crie uma Pessoa 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 -X POST https://api.stripe.com/v2/core/accounts/
{{ACCOUNT_ID}}
/persons \
  -H "Authorization: Bearer 
sk_test_BQokikJOvBiI2HlWgH4olfQ2
" \
  -H "Stripe-Version: 2025-11-17.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.

Ao testar sua integração, preencha antecipadamente os dados da conta usando dados de teste.

Criar um link da conta

Você pode criar um link de conta chamando a API Account Links v2 com os seguintes parâmetros:

• account
• refresh_url
• return_url
• type = account_onboarding
• configurations = recipient e merchant

curl -X POST https://api.stripe.com/v2/core/account_links \
  -H "Authorization: Bearer 
sk_test_BQokikJOvBiI2HlWgH4olfQ2
" \
  -H "Stripe-Version: 2025-08-27.preview" \
  --json '{
    "account": 
"{{CONNECTED_ACCOUNT_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.

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
    }
}

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.

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 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 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 /v2/core/accounts para recuperar a conta do usuário e verificar se configuration.recipient.capabilities.stripe_balance.stripe_transfers.status está ativo. Se o status não for ativo e configuration.destinatário.capabilities.stripe_balance.stripe_transfers.status_details.code for requirements_past_due, forneça prompts de IU para permitir que o usuário continue a fazer onboarding por meio de um novo link de conta. Para outros códigos, trate-os conforme necessário.

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>
  <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 retornado na resposta.

curl https://api.stripe.com/v1/checkout/sessions \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -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]"=
"{{CONNECTED_ACCOUNT_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. 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.

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.

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.

Gerencie eventos pós-pagamento Server-side

A Stripe envia um evento checkout.session.completed quando o pagamento é concluído. Use um webhook para receber esses eventos 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 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:

Todos esses eventos incluem o objeto Checkout Session. Após o êxito do pagamento, o status subjacente do PaymentIntent passa de processing para succeeded.