Crie cobranças de destino

Crie cobranças na conta da sua plataforma, colete tarifas e transfira imediatamente os fundos restantes para suas contas conectadas.

Crie cobranças de destino quando os clientes fizerem transações com sua plataforma para produtos ou serviços fornecidos por suas contas conectadas e você transferir fundos imediatamente para suas contas conectadas. Com este tipo de cobrança:

Você cria uma cobrança na conta da sua plataforma.
Você determina se alguns ou todos os fundos são transferidos para a conta conectada.
O custo das tarifas da Stripe e de reembolsos ou estornos é debitado da sua conta.

Esse tipo de cobrança é mais ideal para marketplaces como o Airbnb, um marketplace de aluguel residencial, ou a Lyft, um aplicativo de transporte por aplicativo.

Destination Charges só são aceitas se a plataforma e a conta conectada estiverem no mesmo país. Para compatibilidade internacional, você deve especificar o comerciante da liquidação para a conta conectada usando o parâmetro on_behalf_of no Payment Intent ou em outros cenários válidos de transferências internacionais. Recomendamos usar cobranças de destino para contas conectadas que têm acesso ao Dashboard Express ou nenhum 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 o Stripe Elements. O código no lado do cliente e do servidor cria um formulário de checkout que aceita várias formas de pagamento. Compare esta integração com as outras formas 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 no 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 deixar que a Stripe obtenha automaticamente as formas de pagamento das configurações do 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 as restrições de moeda, forma de pagamento e outros parâmetros para determinar a lista de formas de pagamento 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 e uma moeda habilitados. 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 processa 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/basil/stripe.js"></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.

Testar 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.

OpcionalHabilite mais formas de pagamento

Coletar tarifas

Quando um pagamento é processado, em vez de transferir o valor total da transação para uma conta conectada, sua plataforma pode decidir cobrar uma parte do valor da transação na forma de tarifas. Você pode definir os preços das tarifas de duas maneiras diferentes:

Use a ferramenta de preços da plataforma para definir e testar as regras de preços das tarifas da plataforma. No momento, esse recurso no-code no Stripe Dashboard só está disponível para plataformas responsáveis pelo pagamento das tarifas da Stripe.
Defina internamente as regras de preços, especificando as tarifas diretamente em um PaymentIntent usando o parâmetro application_fee_amount ou transfer_data[amount]. As tarifas definidas com esse método substituem a lógica de preços especificada na ferramenta de preços da plataforma.

Ao criar cobranças com application_fee_amount, o valor total da cobrança é imediatamente transferido da plataforma para a conta transfer_data[destination] depois que a cobrança é capturada. O valor application_fee_amount (limitado ao valor total da cobrança) é transferido de volta à plataforma em seguida.

Após a coleta da tarifa da plataforma, um objeto Application Fee é criado. Veja uma lista de tarifas da plataforma no Dashboard, com as tarifas da plataforma ou em Sigma. Você também pode usar a propriedade amount no objeto Application Fee para obter relatórios detalhados de tarifas.

Quando usar um application_fee_amount, lembre-se:

O application_fee_amount é limitado ao valor total da transação.
O application_fee_amount é sempre computado na mesma moeda da transação.
A tarifa da plataforma é liquidada na mesma moeda de liquidação da conta conectada. Para cobranças de destino internacionais, isso pode diferir da moeda de liquidação da sua plataforma.
Sua plataforma paga a tarifa da Stripe após a transferência do application_fee_amount para sua conta.
Nenhuma tarifa da Stripe adicional é aplicada ao valor.
Sua plataforma pode usar relatórios integrados de tarifas da plataforma para reconciliar as tarifas cobradas.
Em dashboards ou componentes hospedados na Stripe como o componente de detalhes do pagamento, sua conta conectada pode visualizar o valor total e o valor da tarifa da plataforma.

Fluxo de fundos

Com o código acima, o valor total da cobrança (US$ 10,00) é adicionado ao saldo pendente da conta conectada. O valor application_fee_amount (US$ 1,23) é subtraído do valor da cobrança e transferido para sua plataforma. As tarifas da Stripe (US$ 0,59) são subtraídas do saldo da conta da plataforma. O valor da tarifa da plataforma, deduzido das tarifas da Stripe (US$ 1,23 - US$ 0,59 = US$ 0,64), permanece no saldo da conta da plataforma.

O application_fee_amount é disponibilizado no cronograma de transferências normal da conta da plataforma, assim como os fundos das cobranças normais da Stripe.

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.

Emitir reembolsos

Se você está usando a API Payment Intents, os reembolsos devem ser emitidos para a cobrança criada mais recentemente.

As cobranças criadas na conta da plataforma podem ser reembolsadas usando a chave secreta da conta da plataforma. No reembolso de uma cobrança que tem transfer_data[destination], por padrão, a conta de destino mantém os fundos que foram transferidos para ela e o saldo negativo do reembolso é coberto pela conta da plataforma. Para recuperar os fundos da conta conectada a fim de cobrir o reembolso, defina o parâmetro reverse_transfer como true na criação do reembolso:

Por padrão, o valor total da cobrança é reembolsado, mas você pode criar um reembolso parcial definindo amount como um inteiro positivo.

Se o valor total da cobrança é reembolsado, toda a transferência é anulada. Caso contrário, um valor proporcional da transferência é anulado.

Reembolsar tarifas da plataforma

Quando você reembolsa uma cobrança com uma tarifa da plataforma, por padrão, a conta da plataforma mantém os fundos da tarifa da plataforma. Para devolver esses fundos para a conta conectada, defina o parâmetro refund_application_fee como true na criação do reembolso:

Se você reembolsar a tarifa da plataforma em uma cobrança de destino, precisa anular a transferência. Se o valor total da cobrança é reembolsado, toda a tarifa da plataforma é anulada. Caso contrário, um valor proporcional da tarifa da plataforma é reembolsado.

Você também pode informar um valor false para refund_application_fee e reembolsar a tarifa da plataforma separadamente usando a API.

Reembolsos com falha

Quando um reembolso falha ou você o cancela, o valor do reembolso não finalizado retorna ao seu saldo da conta da plataforma na Stripe. Crie uma transferência se precisar movimentar os fundos para a conta conectada.

Gerenciar contestações

Para cobranças de destino, com ou sem on_behalf_of, a Stripe debita os valores da contestação e as tarifas da conta da sua plataforma.

Recomendamos configurar um webhook para escutar eventos criados por contestação. Se isso acontecer, tente recuperar fundos da conta conectada anulando a transferência pelo Dashboard ou criando uma anulação de transferência.

Se o saldo da conta conectada for negativo, a Stripe tenta debitar sua conta externa se debit_negative_balances estiver definido como true.

Se você desafiar a contestação e vencer, poderá transferir os fundos que devolveu anteriormente para a conta conectada. Se sua plataforma tiver saldo insuficiente, a transferência falhará. Evite erros de saldo insuficiente adicionando fundos ao seu saldo da Stripe.

Erro comum

A retransferência de uma anulação anterior está sujeita a restrições de transferências internacionais, o que significa que você pode não como pagar sua conta conectada. Aguarde para recuperar transferências de pagamento internacionais contestadas para cobranças de destino com on_behalf_of até depois que a contestação for perdida.

Crie cobranças de destino

Crie cobranças na conta da sua plataforma, colete tarifas e transfira imediatamente os fundos restantes para suas 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

Testar a integração

OpcionalHabilite mais formas de pagamento

Coletar tarifas

Fluxo de fundos

Especificar o comerciante da liquidação

Cuidado

Emitir reembolsos

Reembolsar tarifas da plataforma

Reembolsos com falha

Gerenciar contestações

Erro comum

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