Receba pagamentos e efetue repasses em seu marketplace

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

# Available as a gem
sudo gem install stripe

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

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.

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

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.

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.

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.

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.

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.

Página hospedada pela Stripe

Formulário integrado

Fluxo personalizado

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:

Evento	Descrição	Próximas etapas
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	O pagamento do cliente foi confirmado.	Execute o pedido de mercadorias ou serviços.
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. Após o êxito do pagamento, o status subjacente do PaymentIntent passa de processing para succeeded.

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

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