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:

Alemanha

Austrália

Áustria

Bélgica

Brasil

Bulgária

Canadá

Chipre

Croácia

Dinamarca

Eslováquia

Eslovênia

Espanha

Estados Unidos

Estônia

Finlândia

França

Grécia

Hungria

Irlanda

Itália

Japão

Letônia

Liechtenstein

Lituânia

Luxemburgo

Malásia

Malta

México

Noruega

Nova Zelândia

Países Baixos

Polônia

Portugal

Reino Unido

República Tcheca

Romênia

Singapura

Suécia

Suíça

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_behalf_of, 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.

Web

iOS

Android

React Native

Crie uma integração de pagamentos personalizada incorporando componentes de IU ao seu site com Stripe Elements. O código no lado do cliente e no lado do servidor cria um formulário de checkout que aceita várias formas de pagamento. Veja como essa integração se compara a outros tipos de integração da Stripe.

Para ver como o Link funciona para um usuário recorrente, digite o e-mail demo@stripe.com. Para ver como o Link funciona durante um novo cadastro, insira qualquer outro e-mail e preencha o restante do formulário. Esta demonstração só exibe o Google Pay ou Apple Pay se você tiver um cartão ativo com qualquer uma das carteiras.

Esforço de integração

Alguma programação

Tipo de integração

Combine componentes de IU em um fluxo de pagamento personalizado

Personalização da IU

Personalização em nível de CSS com a API Appearance

Primeiro, cadastre-se para obter uma conta Stripe.

Use nossas bibliotecas oficiais para acessar a API da Stripe no seu aplicativo:

Criar um PaymentIntent
Lado do servidor

A Stripe usa um objeto PaymentIntent para representar sua intenção de coletar o pagamento de um cliente, acompanhando suas tentativas de cobrança e alterações no estado do pagamento durante todo o processo.

As formas de pagamento mostradas aos clientes durante o processo de checkout também estão incluídas no PaymentIntent. Você pode permitir que a Stripe extraia automaticamente as formas de pagamento das suas configurações de Dashboard ou listá-las manualmente.

A menos que sua integração exija uma opção baseada em código para oferecer formas de pagamento, não liste as formas de pagamento manualmente. 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. A Stripe prioriza as formas de pagamento que ajudam a aumentar a conversão e são mais relevantes para a moeda e a localização do cliente. A Stripe oculta as formas de pagamento de prioridade menor em um menu de navegação.

Crie um PaymentIntent no seu servidor com um valor, uma moeda e um valor de transfer_group para associar posteriormente à transferência de fundos. Na versão mais recente da API, especificar o parâmetro automatic_payment_methods é opcional porque a Stripe habilita sua funcionalidade por padrão. Você pode gerenciar formas de pagamento no Dashboard. A Stripe gerencia a devolução de formas de pagamento qualificadas com base em fatores como valor, moeda e fluxo de pagamento da transação.

Recuperar o segredo do cliente

O PaymentIntent inclui um segredo do cliente que o lado do cliente usa para concluir com segurança o processo de pagamento. Você pode usar abordagens diferentes para enviar a senha do cliente ao lado do cliente.

Recupere o segredo do cliente de um endpoint do servidor usando a função fetch do navegador. Essa abordagem é melhor quando o lado do cliente é um aplicativo com uma única página, principalmente se criado com uma estrutura de front-end moderna como o React. Crie o endpoint do servidor que envia o segredo do cliente:

Em seguida, obtenha o segredo do cliente com JavaScript no lado do cliente:

(async () => {
  const response = await fetch('/secret');
  const {client_secret: clientSecret} = await response.json();
  // Render the form using the clientSecret
})();

Coletar dados de pagamento
Lado do cliente

Colete dados de pagamento no cliente com o Payment Element. O Payment Element é um componente de IU que simplifica a coleta de dados de pagamento para diversas formas de pagamento.

O Payment Element contém um iframe que envia com segurança os dados de pagamento à Stripe por uma conexão HTTPS. Evite colocar o Payment Element dentro de outro iframe porque algumas formas de pagamento exigem redirecionamento para outra página para confirmação do pagamento.

Se você optar por usar um iframe e quiser aceitar Apple Pay ou Google Pay, o iframe deve ter o atributo de permissão definido como "payment *".

O endereço da página de checkout deve começar com https:// em vez de http:// para que sua integração funcione. Você pode testar a integração sem usar HTTPS, mas lembre-se de habilitar HTTPS quando estiver pronto para aceitar pagamentos em tempo real.

Configurar o Stripe.js

O Payment Element está automaticamente disponível como um recurso do Stripe.js. Inclua o script Stripe.js em sua página de checkout adicionando-o ao head do arquivo HTML. Sempre carregue Stripe.js diretamente de js.stripe.com para manter a conformidade com PCI. Não inclua o script em um pacote nem hospede pessoalmente uma cópia dele.

checkout.html
<head>
  <title>Checkout</title>
  <script src="https://js.stripe.com/v3/"></script>
</head>

Crie uma instância de Stripe com o seguinte JavaScript em sua página de checkout:

checkout.js
// Set your publishable key: remember to change this to your live publishable key in production
// See your keys here: https://dashboard.stripe.com/apikeys
const stripe = Stripe('pk_test_TYooMQauvdEDq54NiTphI7jx'
);

Adicione o Element Pagamento à sua página de pagamentos

O Payment Element precisa de um lugar para residir na sua página de pagamentos. Crie um node DOM vazio (contêiner) com um ID único no seu formulário de pagamento:

checkout.html
<form id="payment-form">
  <div id="payment-element">
    <!-- Elements will create form elements here -->
  </div>
  <button id="submit">Submit</button>
  <div id="error-message">
    <!-- Display error message to your customers here -->
  </div>
</form>

Quando o formulário anterior for carregado, crie uma instância do Payment Element e monte-a no nó DOM do contêiner. Passe o segredo do cliente da etapa anterior em options quando criar a instância do Elements:

Administre cuidadosamente o segredo do cliente, pois ele pode finalizar a cobrança. Não registre em log, incorpore em URLs nem exponha esse segredo a ninguém, exceto para o próprio cliente.

checkout.js
const options = {
  clientSecret: '{{CLIENT_SECRET}}',
  // Fully customizable with appearance API.
  appearance: {/*...*/},
};

// Set up Stripe.js and Elements to use in checkout form, passing the client secret obtained in a previous step
const elements = stripe.elements(options);

// Create and mount the Payment Element
const paymentElementOptions = { layout: 'accordion'};
const paymentElement = elements.create('payment', paymentElementOptions);
paymentElement.mount('#payment-element');

O Payment Element renderiza um formulário dinâmico que permite ao cliente escolher uma forma de pagamento. Para cada forma de pagamento, o formulário solicita automaticamente que o cliente preencha todos os dados de pagamento necessários.

Personalizar a aparência

Personalize o Payment Element para corresponder ao design do seu site, passando o objeto appearance para options ao criar o provedor do Elements.

Solicitar endereços

Por padrão, o Payment Element coleta apenas os detalhes necessários do endereço de cobrança. Para coletar o endereço de cobrança completo (por exemplo, para calcular o imposto para mercadorias e serviços digitais) ou o endereço de entrega de um cliente, use o Address Element.

Solicitar token de comerciante do Apple Pay

Se tiver configurado sua integração para aceitar pagamentos Apple Pay, recomendamos configurar a interface do Apple Pay para retornar um token de comerciante que habilite transações iniciadas por comerciante (MIT). Solicite o tipo de token de comerciante pertinente no Payment Element.

Enviar o pagamento para a Stripe
Lado do cliente

Use stripe.confirmPayment para concluir o pagamento utilizando os detalhes do Payment Element. Forneça um return_url a essa função para indicar para onde a Stripe deve redirecionar o usuário após a conclusão do pagamento. Seu usuário pode ser redirecionado primeiro para um site intermediário, como uma página de autorização bancária, antes de ser redirecionado para o return_url. Os pagamentos com cartão são redirecionados imediatamente para o return_url quando um pagamento é finalizado.

Se não quiser redirecionar pagamentos com cartão após a conclusão do pagamento, defina redirecionar como if_required. Isso somente redireciona os clientes que fazem checkout com formas de pagamento baseadas em redirecionamento.

checkout.js
const form = document.getElementById('payment-form');

form.addEventListener('submit', async (event) => {
  event.preventDefault();

  const {error} = await stripe.confirmPayment({
    //`Elements` instance that was used to create the Payment Element
    elements,
    confirmParams: {
      return_url: 'https://example.com/order/123/complete',
    },
  });

  if (error) {
    // This point will only be reached if there is an immediate error when
    // confirming the payment. Show error to your customer (for example, payment
    // details incomplete)
    const messageContainer = document.querySelector('#error-message');
    messageContainer.textContent = error.message;
  } else {
    // Your customer will be redirected to your `return_url`. For some payment
    // methods like iDEAL, your customer will be redirected to an intermediate
    // site first to authorize the payment, then redirected to the `return_url`.
  }
});

Verifique se o return_url corresponde a uma página no seu site que fornece o status do pagamento. Quando a Stripe redireciona o cliente para o return_url, nós fornecemos os seguintes parâmetros de consulta de URL:

Parâmetro	Descrição
`payment_intent`	O identificador único do `PaymentIntent`.
`payment_intent_client_secret`	O segredo do cliente do objeto `PaymentIntent`.

Cuidado

Se você tiver ferramentas que rastreiam a sessão do cliente no navegador, pode ser necessário adicionar o domínio stripe.com à lista de exclusão de referenciadores. Os redirecionamentos fazem com que algumas ferramentas criem novas sessões, o que impede que você rastreie a sessão completa.

Use um dos parâmetros de consulta para recuperar o PaymentIntent. Inspecione o status do PaymentIntent para decidir o que mostrar aos clientes. Você também pode anexar seus próprios parâmetros de consulta ao fornecer o return_url, que persiste durante o processo de redirecionamento.

status.js
// Initialize Stripe.js using your publishable key
const stripe = Stripe('pk_test_TYooMQauvdEDq54NiTphI7jx'
);

// Retrieve the "payment_intent_client_secret" query parameter appended to
// your return_url by Stripe.js
const clientSecret = new URLSearchParams(window.location.search).get(
  'payment_intent_client_secret'
);

// Retrieve the PaymentIntent
stripe.retrievePaymentIntent(clientSecret).then(({paymentIntent}) => {
  const message = document.querySelector('#message')

  // Inspect the PaymentIntent `status` to indicate the status of the payment
  // to your customer.
  //
  // Some payment methods will [immediately succeed or fail][0] upon
  // confirmation, while others will first enter a `processing` state.
  //
  // [0]: https://stripe.com/docs/payments/payment-methods#payment-notification
  switch (paymentIntent.status) {
    case 'succeeded':
      message.innerText = 'Success! Payment received.';
      break;

    case 'processing':
      message.innerText = "Payment processing. We'll update you when payment is received.";
      break;

    case 'requires_payment_method':
      message.innerText = 'Payment failed. Please try another payment method.';
      // Redirect your user back to your payment page to attempt collecting
      // payment again
      break;

    default:
      message.innerText = 'Something went wrong.';
      break;
  }
});

Gerenciar eventos pós-pagamento
Lado do servidor

Stripe envia um evento payment_intent.succeeded quando o pagamento é concluído. Use a ferramenta Dashboard webhook ou siga o guia de webhooks para receber esses eventos e executar ações, como enviar um e-mail de confirmação do pedido ao cliente, registrar a venda em um banco de dados ou iniciar um fluxo de trabalho de envio.

Escute esses eventos em vez de aguardar um retorno de chamada do cliente. No cliente, o consumidor pode fechar a janela do navegador ou sair do aplicativo antes da execução do retorno de chamada, o que permite que clientes mal-intencionados manipulem a resposta. 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 payment_intent.succeeded, recomendamos gerenciar esses outros eventos ao coletar pagamentos com o Element Pagamento:

Evento	Descrição	Ação
payment_intent.succeeded	Enviado quando um cliente conclui um pagamento com êxito.	Envie ao cliente uma confirmação de pedido e processe o pedido.
payment_intent.processing	Enviado quando um cliente inicia um pagamento, mas o pagamento ainda precisa ser concluído. Esse evento costuma ser enviado quando um cliente inicia um débito bancário. Ele é seguido por um evento `payment_intent.succeeded` ou `payment_intent.payment_failed` no futuro.	Envie ao cliente uma confirmação do pedido que indica que o pagamento está pendente. Para produtos digitais, pode ser necessário executar o pedido antes de aguardar a conclusão do pagamento.
payment_intent.payment_failed	Enviado quando um cliente tenta fazer um pagamento, mas o pagamento falha.	Se um pagamento passa de `processing` para `payment_failed`, ofereça ao cliente outra tentativa para pagar.

Criar uma transferência
Lado do servidor

No seu servidor, envie fundos da sua conta para uma conta conectada criando uma Transferência e especificando o transfer_group 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_group.

Opções de transferência

Você pode atribuir qualquer valor à string transfer_group, 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_group. Por exemplo, quando você paga um provedor, mas não há um pagamento a cliente associado.

Observação

O transfer_group 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_transaction 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_transaction definida.

Teste a integração

Número do cartão	Cenário	Como 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.

OpcionalHabilitar formas de pagamento adicionais

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_behalf_of para o ID de uma conta conectada para tornar essa conta o comerciante de liquidação do pagamento. Quando usar on_behalf_of:

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_behalf_of for omitido, a plataforma será a empresa registrada para o pagamento.

Cuidado

O parâmetro on_behalf_of 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_payments 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.

Como uma cobrança é dividida em tarifas para a conta da plataforma e transferências para as contas conectadas

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_transaction. Com um source_transaction, 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_group, a Stripe atribui o mesmo valor ao transfer_group 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_pi_2NHDDD589O8KAxCG0179Du2s. Essa string é atribuída como transfer_group tanto para a cobrança quanto para a transferência.

Observação

Você deve especificar o source_transaction 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_intent na solicitação. Esse método retorna dados completos para todas as cobranças associadas ao PaymentIntent.

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_transaction, desde que a soma das transferências não exceda a cobrança de origem
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_group para você
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_transaction 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_transaction com esses pagamentos, será preciso implementar funcionalidades para gerenciar falhas nos pagamentos.

Quando um pagamento usado como source_transaction 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_transaction 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.

Criar cobranças e transferências separadas

Crie cobranças na conta da sua plataforma e transfira fundos para várias contas conectadas.

Visualização privada

Esforço de integração

Tipo de integração

Personalização da IU

Criar um PaymentIntentLado do servidor

Recuperar o segredo do cliente

Coletar dados de pagamentoLado do cliente

Configurar o Stripe.js

Adicione o Element Pagamento à sua página de pagamentos

Personalizar a aparência

Solicitar endereços

Solicitar token de comerciante do Apple Pay

Enviar o pagamento para a StripeLado do cliente

Cuidado

Gerenciar eventos pós-pagamentoLado do servidor

Criar uma transferênciaLado do servidor

Opções de transferência

Observação

Observação

Teste a integração

OpcionalHabilitar formas de pagamento adicionais

Especificar o comerciante da liquidação

Cuidado

Coletar tarifas

Disponibilidade da transferência

Observação

Observação

Emita reembolsos

Anulará transferências

Veja também

Criar um PaymentIntent
Lado do servidor

Coletar dados de pagamento
Lado do cliente

Enviar o pagamento para a Stripe
Lado do cliente

Gerenciar eventos pós-pagamento
Lado do servidor

Criar uma transferência
Lado do servidor