Pular para o conteúdo
Criar conta
ou
Entrar
O logotipo da documentação da Stripe
/
Pergunte à IA
Criar conta
Login
Comece já
Pagamentos
Receita
Plataformas e marketplaces
Gestão de valores
Recursos para desenvolvedores
Visão geral
Comece a usar o Connect
Princípios básicos de integração
Exemplos de integrações
    Criar um marketplace
    Criar uma plataforma de SaaS
    Cobra tarifas de SaaS para contas conectadas
    Criar uma integração do Connect totalmente incorporada
Gerenciamento de contas
Fazer onboarding de contas
Configurar Dashboards da conta
Trabalhe com tipos de contas conectadas
Processamento de pagamentos
Receba pagamentos
Repassar para contas
Administração de plataforma
Gerencie sua plataforma do Connect
Informes fiscais para sua plataforma Connect
Página inicialPlataformas e marketplacesExample integrations

Receba pagamentos e efetue repasses em seu marketplace

Receba pagamentos de clientes e repasse-os para vendedores ou prestadores de serviços no seu marketplace.

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.
  2. Adicione dados da empresa para ativar sua conta.
  3. Conclua seu perfil da plataforma.
  4. Personalize as configurações da sua marca. 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:

Command Line
Ruby
# Available as a gem sudo gem install stripe
Gemfile
Ruby
# If you use bundler, you can add this line to your Gemfile gem 'stripe'

Criar uma conta conectada

Quando um usuário (vendedor ou provedor de serviços) se cadastrar no seu marketplace, crie uma conta de usuário (chamada de conta conectada). Você pode aceitar pagamentos e enviar valores para a conta bancária do usuário sem uma conta conectada. As contas conectadas representam seus usuários na API Stripe e coletam os dados necessários para verificar a identidade do usuário. No exemplo de locação residencial, a conta conectada representa o proprietário do imóvel.

Crie uma conta conectada e preencha os dados

Use a API /v1/accounts para criar uma conta conectada especificando as propriedades da conta conectada ou o tipo de conta.

Command Line
cURL
curl https://api.stripe.com/v1/accounts \ -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:"
\ -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.

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.

Crie um link de conta

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

  • account
  • refresh_url
  • return_url
  • type = account_onboarding
Command Line
cURL
curl https://api.stripe.com/v1/account_links \ -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:"
\ -d account=
{{CONNECTED_ACCOUNT_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 à solicitação da API Account Links inclui um valor para a chave url. Redirecione para esse link para enviar o usuário ao fluxo. URLs da API Account Links são temporários e usados somente uma vez, porque concedem acesso aos dados pessoais do usuário da conta conectada. Autentique o usuário no aplicativo antes de redirecioná-lo para esse URL. Se quiser preencher as informações, faça-o antes de gerar o link da conta. Após criar o link para a conta, não é possível ler ou gravar informações na conta conectada.

Dica de segurança

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.

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.

Observação

Para return_url e refresh_url, você pode usar HTTP enquanto estiver em um ambiente de teste (por exemplo, para testar com localhost), mas o modo de produção só aceita HTTPS. Não se esqueça de trocar os URLs de teste para HTTPS antes de entrar em modo de produção.

return_url

A Stripe emite um redirecionamento para este URL quando o usuário conclui o fluxo do Connect Onboarding. Isso não significa que todas as informações foram coletadas ou que não há requisitos pendentes na conta. Significa somente que a entrada e saída do fluxo foram normais.

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:

  • Escutar webhooks account.updated
  • Chamar a API Accounts e inspecionar 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.

O refresh_url deve acionar um método no servidor para chamar novamente a API Account Links com os mesmos parâmetros e redirecionar o usuário ao fluxo do Connect Onboarding para criar uma experiência ideal.

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

Um usuário que é redirecionado para o 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 charges_enabled. Se a conta não estiver totalmente integrada, forneça solicitações de IU para permitir que o usuário continue o onboarding mais tarde. O usuário pode concluir a ativação da conta por meio de um novo link de conta (gerado por sua integração). Verifique o estado do parâmetro details_submitted na conta dele para ver se o processo de onboarding foi concluído.

Habilitar formas de pagamento

Veja as configurações de formas de pagamento 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 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.

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.

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

Command Line
cURL
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" \ --data-urlencode cancel_url="https://example.com/cancel"
  • 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.
  • cancel_url - este argumento redireciona um usuário que clicou em Cancelar.
  • 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 precisar controlar o cronograma das transferências ou transferir fundos de um único pagamento para várias partes, use cobranças e transferências separadas. Para usar cobranças separadas, consulte Permitir que outras empresas aceitem pagamentos diretamente.

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:

EventoDescriçãoPróximas etapas
checkout.session.completedO cliente autorizou o pagamento enviando o formulário do Checkout.Aguarde a confirmação ou falha do pagamento.
checkout.session.async_payment_succeededO pagamento do cliente foi confirmado.Execute o pedido de mercadorias ou serviços.
checkout.session.async_payment_failedO 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. Após o êxito do pagamento, o status subjacente do PaymentIntent passa de processing para succeeded.

Testes

Teste seu fluxo de criação de conta criando contas e usando OAuth.

Número do cartãoCenárioComo testar
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.
O pagamento com cartã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.
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.
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.

Consulte Testes para obter mais informações sobre como testar sua integração.

Contestações

Como comerciante de liquidação das cobranças, sua plataforma é responsável pelas contestações. Leia com atenção as práticas recomendadas para responder a contestações.

Repasses

Por padrão, todos os fundos transferidos para uma conta conectada são acumulados no saldo Stripe da conta conectada e repassados diariamente. É possível alterar a frequência dos repasses 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. 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.

Observação

Contas conectadas não podem iniciar reembolsos para pagamentos no Dashboard Express. Se suas contas conectadas usam o Dashboard Express, você deve processar os reembolsos para elas.

Veja também

  • Gerenciar contas conectadas no Dashboard
  • Emitir reembolsos
  • Personalizar descrições no extrato
  • Trabalhar com várias moedas
Esta página foi útil?
SimNão
Precisa de ajuda? Fale com o suporte.
Participe do nosso programa de acesso antecipado.
Confira nosso changelog.
Dúvidas? Fale com a equipe de vendas.
LLM? Read llms.txt.
Powered by Markdoc