Criar cobranças e transferências separadas
Crie cobranças na conta da sua plataforma e transfira fundos para várias contas conectadas.
Crie cobranças e transferências separadas para transferir fundos de um pagamento para várias contas conectadas ou quando um usuário específico não for conhecido no momento do pagamento. A cobrança na conta da sua plataforma é desvinculada das transferências para suas contas conectadas. Com este tipo de cobrança:
- Você cria uma cobrança na conta da sua plataforma e transfere fundos para suas contas conectadas. O pagamento aparece como cobrança na sua conta, e também há transferências para contas conectadas (valor determinado por você), que são retiradas do saldo da sua conta.
- Você pode transferir os fundos para diferentes contas conectadas.
- O custo das tarifas da Stripe e de reembolsos ou estornos é debitado da sua conta.
Esse tipo de cobrança é mais ideal para marketplaces que precisam dividir pagamentos entre várias partes, como a DoorDash, uma plataforma de entregas para restaurantes.
A Stripe aceita cobranças e transferências separadas nas seguintes regiões:
Na maioria dos cenários, sua plataforma e todas as contas conectadas precisam estar na mesma região. A tentativa de transferir fundos para uma região não permitida retorna um erro. Para obter informações sobre o suporte entre regiões, consulte as transferências internacionais. Você só pode usar transferências em combinação com os casos de uso permitidos para cobranças, recargas e tarifas. Recomendamos usar cobranças e transferências separadas para contas conectadas com acesso ao Dashboard Express ou sem acesso Dashboard.
Visualização privada
Você pode usar cobranças de destino, sem o parâmetro on_, quando sua plataforma e conta conectada estão em países diferentes, nos EUA, no Reino Unido e na UE. Para ter acesso antecipado, fale conosco.
Redirecione para uma página de pagamento hospedada pela Stripe usando o Stripe Checkout. Veja como essa integração se compara a outros tipos de integração da Stripe.
Esforço de integração
Tipo de integração
Redirecionar para a página de pagamento hospedada pela Stripe
Personalização da IU
Primeiro, cadastre-se para obter uma conta Stripe.
Use nossas bibliotecas oficiais para acessar a API da Stripe no seu aplicativo:
Criar uma sessão do CheckoutLado do clienteLado do servidor
Uma Checkout Session controla o que o seu cliente vê no formulário de pagamento, como itens de linha, o valor e a moeda do pedido, bem como formas de pagamento aceitáveis. 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 seu servidor, crie uma sessão do Checkout e redirecione o cliente para o URL retornado na resposta.
line_– este atributo representa os itens que o cliente está comprando. Os itens são exibidos na página de checkout hospedada pela Stripe.items payment_– use uma string exclusiva comointent_ data[transfer_ group] transfer_para identificar objetos associados entre si. Quando a Stripe cria automaticamente uma cobrança para uma PaymentIntent com um valor degroup transfer_, atribui o mesmo valor aogroup transfer_da cobrança.group success_- A Stripe redireciona o cliente para o URL de êxito após a conclusão de um pagamento e substitui a stringurl {CHECKOUT_pelo ID da sessão do Checkout. Use isso para acessar a sessão do Checkout e inspecionar o status para decidir o que mostrar ao cliente. Você também pode anexar seus próprios parâmetros de consulta, que permanecem durante o processo de redirecionamento. Consulte personalizar o comportamento de redirecionamento com uma página hospedada pela Stripe para saber mais.SESSION_ ID}
Gerenciar eventos pós-pagamentoLado do servidor
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.
A Stripe recomenda gerenciar todos os eventos a seguir ao receber 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 a realização de um novo pedido. |
Todos esses eventos incluem o objeto Checkout Session. Após o pagamento, o status subjacente do PaymentIntent muda de processing para succeeded ou um status malsucedido.
Criar uma transferênciaLado do servidor
No seu servidor, envie fundos da sua conta para uma conta conectada criando uma Transferência e especificando o transfer_ utilizado.
Os valores de transferência e cobrança não precisam ser iguais. Você pode dividir uma única cobrança entre várias transferências ou incluir várias cobranças em uma única transferência. O exemplo a seguir cria uma transferência adicional associada ao mesmo transfer_.
Opções de transferência
Você pode atribuir qualquer valor à string transfer_, mas ela deve representar uma única ação de negócios. Também é possível fazer uma transferência sem associar uma cobrança ou transfer_. Por exemplo, quando você paga um provedor, mas não há um pagamento a cliente associado.
Observação
O transfer_ identifica apenas objetos associados. Ele não afeta nenhuma funcionalidade padrão. Para evitar que uma transferência seja executada antes que os fundos da cobrança associada estejam disponíveis, use o atributo source_ da transferência.
Por padrão, uma solicitação de transferência falha quando o valor excede o saldo da conta disponível da plataforma. A Stripe não repete automaticamente solicitações de transferência malsucedidas.
Você pode evitar falhas nas solicitações de transferência para transferências associadas a cobranças. Quando você especifica a cobrança associada como a source_transaction da transferência, a solicitação de transferência é bem-sucedida automaticamente. No entanto, não executamos a transferência até que os fundos dessa cobrança estejam disponíveis na conta da plataforma.
Observação
Se você usa cobranças e transferências separadas, leve isso em consideração quando planejar seu cronograma de repasses payout. Repasses automáticos podem interferir nas transferências que não têm uma source_ definida.
Teste a integração
Consulte Testes para obter mais informações sobre como testar sua integração.
Especificar o comerciante da liquidação
O comerciante da liquidação depende das funções da conta e da forma de criação da cobrança. O comerciante da liquidação determina quais dados são usados para fazer a cobrança. Isso inclui a descrição no extrato (da plataforma ou da conta conectada) exibida sobre essa cobrança no extrato bancário ou de cartão de crédito do cliente.
A especificação do comerciante da liquidação permite que você defina mais explicitamente para quem as cobranças são criadas. Por exemplo, algumas plataformas preferem ser o comerciante da liquidação porque o cliente final interage diretamente com a plataforma (como plataformas sob demanda). No entanto, algumas plataformas têm contas conectadas que interagem diretamente com os clientes finais (como lojas de uma plataforma de e-commerce). Nesses cenários, pode fazer mais sentido que a conta conectada seja o comerciante da liquidação.
Você pode definir o parâmetro on_ para o ID de uma conta conectada para tornar essa conta o comerciante de liquidação do pagamento. Quando usar on_:
- As cobranças são liquidadas no país da conta conectada e na moeda de liquidação.
- É usada a estrutura de tarifas do país da conta conectada.
- A descrição no extrato da conta conectada é exibida no extrato do cartão de crédito do cliente.
- Se a conta conectada estiver em um país diferente do da plataforma, o endereço e o número de telefone da conta conectada serão exibidos no extrato do cartão de crédito do cliente.
- O número de dias que um saldo pendente é retido antes de receber o repasse depende da configuração delay_days na conta conectada.
Se on_ for omitido, a plataforma será a empresa registrada para o pagamento.
Cuidado
O parâmetro on_ só é aceito para contas conectadas com uma função de pagamentos, como card_payments. As contas sujeitas ao contrato de serviços de destinatário não podem solicitar card_ nem outras funções de pagamento.
Coletar tarifas
Ao usar cobranças e transferências separadas, a plataforma pode coletar tarifas sobre uma cobrança, reduzindo o valor transferido para as contas de destino. Por exemplo, considere uma transação de serviço de entrega em restaurante que envolve pagamentos ao restaurante e ao motorista:
- O cliente paga uma cobrança de US$ 100.
- A Stripe coleta uma tarifa de US$ 3,20 e adiciona os US$ 96,80 restantes ao saldo pendente da conta da plataforma.
- A plataforma transfere US$ 70 para a conta conectada do restaurante e US$ 20 para a conta conectada do motorista.
- Uma tarifa de plataforma de US$ 6,80 permanece na conta da plataforma.
Para saber mais sobre o processamento de pagamentos em várias moedas com o Connect, consulte como trabalhar com várias moedas.
Disponibilidade da transferência
O comportamento padrão é transferir fundos do saldo disponível da conta da plataforma. A tentativa de uma transferência que excede o saldo disponível falha com um erro. Para evitar esse problema, quando criar uma transferência, vincule-a a uma cobrança existente especificando o ID da cobrança como o parâmetro source_. Com um source_, a solicitação de transferência retorna com êxito, independentemente do seu saldo disponível, caso a cobrança relacionada ainda não tenha sido liquidada. No entanto, os fundos não ficam disponíveis na conta de destino até que os fundos da cobrança associada estejam disponíveis para transferência da conta da plataforma.
Observação
Se uma transferência falhar por falta de fundos no saldo da plataforma, a adição de fundos não acionará automaticamente uma nova tentativa da ação malsucedida. Depois de adicionar fundos, você deve repetir todas as transferências ou repasses malsucedidos.
Se a cobrança de origem tiver um valor transfer_, a Stripe atribui o mesmo valor ao transfer_ da transferência. Se isso não acontecer, a Stripe gera uma cadeia de caracteres no formato group_ mais o ID do PaymentIntent associado, por exemplo: group_. Essa string é atribuída como transfer_ tanto para a cobrança quanto para a transferência.
Observação
Você deve especificar o source_ quando criar uma transferência. Não é possível atualizar esse atributo posteriormente.
Você pode obter o ID da cobrança no PaymentIntent:
- Obtenha o atributo latest_charge do PaymentIntent. Este atributo é o ID da cobrança mais recente associada ao PaymentIntent.
- Solicitar uma lista de cobranças, especificando o
payment_na solicitação. Esse método retorna dados completos para todas as cobranças associadas ao PaymentIntent.intent
Quando esse parâmetro é usado:
- O valor da transferência não pode exceder o valor da cobrança de origem
- Você pode criar várias transferências com o mesmo
source_, desde que a soma das transferências não exceda a cobrança de origemtransaction - A transferência assume o status pendente da cobrança associada. Se os fundos da cobrança são disponibilizados em N dias, o pagamento recebido da transferência pela conta Stripe de destino também é disponibilizado em N dias
- A Stripe cria automaticamente um
transfer_para vocêgroup - A moeda da transação de saldo associada com a cobrança precisa corresponder à moeda da transferência
Formas de pagamento assíncronas, como ACH, podem falhar após ser feita uma solicitação de transferência subsequente. Evite usar source_ para esses pagamentos. Em vez disso, aguarde o acionamento de um evento charge.succeeded antes de transferir os fundos. Se for necessário usar source_ com esses pagamentos, será preciso implementar funcionalidades para gerenciar falhas nos pagamentos.
Quando um pagamento usado como source_ falha, os fundos no saldo da conta da sua plataforma são transferidos para a conta conectada para cobrir o pagamento. Para recuperar esses fundos, anule a transferência associada ao source_ malsucedido.
Emita reembolsos
Você pode reembolsar cobranças criadas em sua plataforma usando a chave secreta. No entanto, o reembolso de uma cobrança não afeta nenhuma transferência associada. Cabe à sua plataforma reconciliar qualquer valor devido, reduzindo valores de transferências subsequentes ou anulando transferências.
Anulará transferências
O Connect permite anular transferências para contas conectadas. O valor anulado pode ser total ou parcial, de acordo com o valor definido em amount. Use anulações de transferências somente para reembolsos ou contestações relacionadas à cobrança ou para corrigir erros na transferência.
A anulação de transferências devolve o valor parcial ou total ao saldo disponível da plataforma. O saldo da conta conectada é reduzido no mesmo valor. Só é possível anular uma transferência se o saldo disponível da conta conectada for maior que o valor anulado ou se reservas conectadas estiverem habilitadas na conta.
Se a anulação de transferência exigir uma conversão de moeda e o valor da anulação resultar em um saldo zero após a conversão, ela retornará um erro.
Desativar reembolsos para uma conta conectada não bloqueia a capacidade de processar anulações de transferências.