Pular para o conteúdo
Criar conta
 ou
Entrar
O logotipo da documentação da Stripe
/
Criar conta
Login
Visão geral
Gerenciamento de contas
Processamento de pagamentos
Administração de plataforma

Crie cobranças diretas

Crie cobranças diretamente na conta conectada e receba tarifas.

Crie cobranças diretas quando os clientes fazem transações diretamente com uma conta conectada e muitas vezes nem percebem a existência da sua plataforma. Com cobranças diretas:

  • O pagamento aparece como cobrança na conta conectada, e não na conta da sua plataforma.
  • O saldo da conta conectada aumenta a cada cobrança.
  • O saldo da sua conta aumenta com as tarifas da plataforma de cada cobrança.

Esse tipo de cobrança é mais adequado para plataformas que fornecem software como serviço. A Shopify, por exemplo, oferece ferramentas para a criação de lojas online e a Worksify permite que professores vendam cursos online.

Observação

Recomendamos usar cobranças diretas para contas conectadas que têm acesso ao Stripe Dashboard completo.

Crie uma integração de pagamentos personalizada incorporando componentes de IU ao seu site usando 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.

Localização do cliente
Tamanho
Tema
Layout
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:

Command Line
# Available as a gem
sudo gem install stripe
Gemfile
# If you use bundler, you can add this line to your Gemfile
gem 'stripe'

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

Command Line
curl https://api.stripe.com/v1/payment_intents \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -H "Stripe-Account: 
{{CONNECTED_ACCOUNT_ID}}
" \
  -d amount=1000 \
  -d currency=usd \
  -d "automatic_payment_methods[enabled]"=true \
  -d application_fee_amount=123

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:

main.rb
get '/secret' do
  intent = # ... Create or retrieve the PaymentIntent
  {client_secret: intent.client_secret}.to_json
end

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 uma ampla variedade de formas de pagamento.

O Payment Element contém um iframe que envia dados de pagamento com segurança à Stripe por uma conexão HTTPS. Evite colocar o Payment Element dentro de outro iframe porque algumas formas de pagamento exigem o 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 precisa ter o atributo permitir definido como "payment *" igual.

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 sua integração sem usar HTTPS, mas lembre-se de habilitá-la 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 da Stripe com o seguinte JavaScript na página de checkout:

checkout.js
// Initialize Stripe.js with the same connected account ID used when creating
// the PaymentIntent.
const stripe = Stripe(
'pk_test_TYooMQauvdEDq54NiTphI7jx'
, {
  stripeAccount: 
'{{CONNECTED_ACCOUNT_ID}}'

});

Adicionar o Stripe Elements e o Payment Element à 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">Pay</button>
</form>

Quando o formulário tiver sido carregado, crie uma instância do Payment Element e monte-o no node DOM do contêiner com o segredo do cliente da etapa anterior. Passe esse valor como uma opção quando criar a instância do Elements.

O segredo do cliente precisa ser administrado com cuidado, porque pode finalizar a cobrança. Não armazene, insira em URL nem exponha o segredo para ninguém, exceto para o próprio cliente.

checkout.js
const options = {
  clientSecret: '{{CLIENT_SECRET}}',
  // Fully customizable with the Appearance API
  appearance: {/*...*/},
};
// Set up Stripe.js and Elements to use in checkout form using the client secret
const elements = stripe.elements(options);
// Create and mount the Payment Element
const paymentElement = elements.create("payment");
paymentElement.mount("#payment-element");

O Payment Element renderiza um formulário dinâmico, onde o cliente escolhe uma forma de pagamento. O formulário coleta automaticamente todos os dados de pagamento necessários para a forma de pagamento selecionada pelo cliente. Durante a configuração do objeto Elements, você pode personalizar a aparência do Payment Element de acordo com o design do site.

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âmetroDescrição
payment_intentO identificador único do PaymentIntent.
payment_intent_client_secretO 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:

EventoDescriçãoAção
payment_intent.succeededEnviado quando um cliente conclui um pagamento com êxito.Envie ao cliente uma confirmação de pedido e processe o pedido.
payment_intent.processingEnviado 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_failedEnviado 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ãoCenárioComo 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.

Coletar tarifas

Quando um pagamento é processado, sua plataforma pode receber uma parte da transação na forma de tarifas da plataforma. Você pode definir os preços da tarifa da plataforma de duas maneiras:

  • Use a ferramenta de preços da plataforma para definir e testar regras de preços. 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 da plataforma diretamente em um PaymentIntent. As tarifas definidas com esse método substituem a lógica de preços especificada na ferramenta de preços da plataforma.

Sua plataforma pode cobrar uma tarifa da plataforma com as seguintes limitações:

  • O valor de application_fee_amount deve ser positivo e menor que o valor da cobrança. A tarifa da plataforma cobrada é limitada ao valor capturado da cobrança.
  • Não há tarifas adicionais da Stripe sobre a própria tarifa da plataforma.
  • De acordo com os requisitos regulatórios e de conformidade do Brasil, as plataformas de fora do Brasil com contas conectadas brasileiras não podem coletar tarifas da plataforma por meio da Stripe.
  • A moeda de application_fee_amount depende de alguns fatores de várias moedas.

A transação de saldo da cobrança resultante inclui um detalhamento das tarifas da Stripe e da plataforma. Para melhorar a experiência com os relatórios, é criado um objeto Application Fee após a coleta da tarifa. Use a propriedade amount no objeto de tarifa do aplicativo para criar relatórios. Você pode acessar esses objetos com o endpoint Application Fees.

As tarifas da plataforma recebidas são adicionadas ao saldo disponível da sua conta no mesmo cronograma que os fundos das cobranças regulares da Stripe. Você pode consultá-las na seção Tarifas cobradas do Dashboard.

Cuidado

Por padrão, as tarifas da plataforma para cobranças diretas são criadas de forma assíncrona. Se você expandir o objeto application_fee em uma solicitação de criação de cobrança, a tarifa da plataforma será criada de forma síncrona como parte dessa solicitação. Somente expanda o objeto application_fee se for necessário, pois isso aumenta a latência da solicitação.

Para acessar os objetos de tarifa da plataforma para tarifas da plataforma criadas de forma assíncrona, escute o evento de webhook application_fee.created.

Fluxo de fundos com tarifas

Quando você especifica uma tarifa de plataforma sobre uma cobrança, o valor da tarifa é transferido para a conta da sua plataforma na Stripe. Ao processar uma cobrança diretamente na conta conectada, o valor da cobrança (menos as tarifas da Stripe e da plataforma) é depositado na conta conectada.

Por exemplo, se você fizer uma cobrança de US$ 10 com uma tarifa da plataforma de US$ 1,23 (como no exemplo anterior), US$ 1,23 será transferido para a conta da sua plataforma. US$ 8,18 (US$ 10 - US$ 0,59 - US$ 1,23) são depositados na conta conectada (considerando as tarifas padrão da Stripe dos EUA).

Fluxo de fundos para uma cobrança com uma tarifa da plataforma

Se você processa pagamentos em várias moedas, veja como as moedas são gerenciadas no Connect.

Emitir reembolsos

Além de criar cobranças em contas conectadas, as plataformas também podem criar reembolsos de cobranças em contas conectadas. Crie um reembolso usando a chave secreta da sua plataforma, estando autenticado com as credenciais da conta conectada.

As tarifas da plataforma não são reembolsadas automaticamente quando um reembolso é emitido. Sua plataforma deve reembolsar explicitamente a tarifa da plataforma, caso contrário a conta conectada (a conta na qual a cobrança foi criada) perde esse valor. Você pode reembolsar uma tarifa de plataforma passando um valor refund_application_fee de verdadeiro na solicitação de reembolso:

Command Line
curl https://api.stripe.com/v1/refunds \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -H "Stripe-Account: 
{{CONNECTED_ACCOUNT_ID}}
" \
  -d charge=
{{CHARGE_ID}}
 \
  -d refund_application_fee=true

Por padrão, toda a cobrança é reembolsada, mas você pode criar um reembolso parcial definindo um amount como um número inteiro positivo. Se o reembolso for ao valor total da cobrança, toda a tarifa da plataforma será reembolsada. Caso contrário, um valor proporcional da tarifa da plataforma será reembolsado. Como opção, você pode informar um valor refund_application_fee de falso e reembolsar a tarifa da plataforma separadamente.

Veja também

Esta página foi útil?
SimNão
Precisa de ajuda? Fale com o suporte.
Participe do nosso programa de acesso antecipado.
Confira nosso changelog.
Dúvidas? Fale com a equipe de vendas.
LLM? Read llms.txt.
Powered by Markdoc