Receba e repasse pagamentos
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
- Registre sua plataforma.
- Adicione dados da empresa para ativar sua conta.
- Conclua seu perfil da plataforma.
- Customize your brand settings. Add a business name, icon, and brand color.
Configurar a StripeLado do servidor
Instale as bibliotecas oficiais da Stripe para acessar a API Stripe no seu aplicativo:
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. Você pode criar a conta conectada especificando as propriedades da conta conectada ou o tipo de conta.
Se você já coletou dados de suas contas conectadas, pode usá-los para preencher o objeto da conta. Você pode preencher quaisquer dados de conta, incluindo dados pessoais e comerciais, dados de contas externas e muito mais.
O Connect Onboarding não solicita os dados preenchidos. 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
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 modo 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.
Testes
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.
Contestações
Como comerciante que liquida as 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 da Stripe da conta conectada e são repassados diariamente. É possível alterar a frequência dos repasses na página de detalhes da conta conectada. Para isso, clique no botão mais à direita da seção Saldo e selecione 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.