Permita que as empresas da sua plataforma aceitem pagamentos diretamente

Instale as bibliotecas oficiais da Stripe para acessar a API 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 registra na sua plataforma, crie uma Conta de usuário (chamada de conta conectada) para que você possa aceitar pagamentos e mover fundos para a conta bancária dele. Contas conectadas representam seu usuário na API da Stripe e ajudam a facilitar a coleta de requisitos de onboarding para que a Stripe possa verificar a identidade do usuário. No nosso exemplo do criador de lojas, a conta conectada representa a empresa que está configurando a loja online.

Crie uma conta conectada e preencha os dados

Use a API /v1/accounts para criar uma conta conectada. Você pode criar a conta conectada usando os parâmetros padrão da conta conectada ou especificando o tipo de conta.

curl -X POST https://api.stripe.com/v1/accounts \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:"

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.

Criar um link da 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

Redirecione o usuário para o 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. Esses links são temporários e podem ser 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 o URL. Se quiser preencher as informações, faça-o antes de gerar o link da conta. Após criar o link da conta, não será possível ler ou gravar informações na conta.

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

O usuário é redirecionado para refresh_url nestes casos:

• O link expirou (alguns minutos se passaram desde a criação do link)
• O usuário já acessou o link (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. Os pagamentos com cartão ficam ativados por padrão, mas você pode ativar e desativar as formas de pagamento conforme a necessidade. Este guia supõe que as formas de pagamento Bancontact, cartões de crédito, EPS, iDEAL, Przelewy24, débito automático SEPA e Sofort estão ativadas.

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.

Incorpore o Stripe Checkout como forma de pagamento para diretamente no seu site ou redirecione os usuários para uma página hospedada pela Stripe para aceitar pagamentos. O Checkout aceita várias formas de pagamento e automaticamente mostra as mais relevantes ao cliente. Você também pode usar o Payment Element, um componente de IU pré-criado e integrado como iframe ao seu formulário de pagamento, para aceitar várias formas de pagamento com uma só integração de front-end.

Página hospedada pela Stripe

Formulário integrado

Fluxo personalizado

Crie uma Sessão do Checkout Lado do cliente Lado do servidor

Uma sessão do Checkout controla o que seu cliente vê no formulário de pagamento integrável, como itens de linha, valor e moeda do pedido e formas de pagamento aceitas. Quando realiza cobranças diretas, o Checkout usa as configurações de marca da conta conectada. Consulte a seção Personalizar a marca para obter mais informações.

Ao contrário de cobranças de destino e cobranças e transferências separadas, os usuários (as contas conectadas) são responsáveis por gerenciar contestações de cobranças diretas. Essa responsabilidade não é da plataforma.

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
:" \
  -H "Stripe-Account: 
{{CONNECTED_ACCOUNT_ID}}
" \
  -d mode=payment \
  -d "line_items[0][price]"=
{{PRICE_ID}} \
  -d "line_items[0][quantity]"=1 \
  -d "payment_intent_data[application_fee_amount]"=123 \
  --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.
• 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.
• Stripe-Account – este cabeçalho indica uma cobrança direta para sua conta conectada. Com cobranças diretas, a conta conectada é responsável por tarifas da Stripe, reembolsos e estornos. A marca da conta conectada é utilizada no Checkout, o que permite aos clientes sentirem que estão interagindo diretamente com o comerciante em vez da plataforma.
• (Opcional) payment_intent_data[application_fee_amount] - este argumento especifica o valor que sua plataforma planeja obter da transação. Após o processamento do pagamento na conta conectada, o application_fee_amount é transferido para a plataforma, e a tarifa da Stripe é deduzida do saldo da conta conectada.

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.

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

Crie contas e use OAuth para testar o fluxo de criação de contas. Teste as configurações das formas de pagamento das contas conectadas: entre em uma das contas de teste e acesse as configurações das formas de pagamento. Teste o fluxo de checkout com suas chaves de teste e uma conta de teste. É possível usar nossos cartões de teste para testar seu fluxo de pagamentos e simular vários resultados de pagamento.