Pular para o conteúdo
Criar conta
 ou
Entrar
O logotipo da documentação da Stripe
/
Criar conta
Login
Visão geralAtualize sua integração
Pagamentos online
Visão geralEncontre seu caso de usoPagamentos gerenciados
Formas de pagamento
Interfaces de pagamento
Cenários de pagamento
Pagamentos presenciais
Muito mais que pagamentos

Aceitar uma transferência bancária

Use a API Payment Intents para aceitar pagamentos por transferência bancária.

Na primeira vez em que você aceita um pagamento por transferência bancária de um cliente, a Stripe gera uma conta bancária virtual para o cliente, que pode ser compartilhada diretamente com ele. Todos os pagamentos futuros por transferência bancária deste cliente são enviados para essa conta bancária. Em alguns países, a Stripe também fornece um número de referência de transferência exclusivo que seu cliente deve incluir em cada transferência para facilitar a correspondência entre a transferência e os pagamentos pendentes. Alguns países têm limites para a quantidade de números de contas bancárias virtuais que você pode criar gratuitamente.

Você encontra uma visão geral das etapas comuns ao aceitar um pagamento por transferência bancária no seguinte diagrama de sequência:

Gerenciar pagamentos a menor e a maior

Com pagamentos por transferência bancária, é possível que o cliente envie a você mais ou menos do que o valor do pagamento esperado. Se o cliente enviar muito pouco, a Stripe financiará parcialmente um Payment Intent em aberto. As faturas não são parcialmente financiadas e permanecem abertas até que os fundos recebidos cubram o valor total da fatura.

Se o cliente enviar mais do que o esperado, a Stripe tentará reconciliar os fundos recebidos com um pagamento em aberto e manter o valor em excesso restante no saldo em dinheiro do cliente. Você encontra mais detalhes sobre como a Stripe gerencia a reconciliação na seção de reconciliação da nossa documentação.

Quando um cliente paga parcialmente:

Quando um cliente paga em excesso:

Gerenciar vários pagamentos ou faturas em aberto

Você pode ter vários pagamentos ou faturas em aberto que podem ser pagos com transferência bancária. Na configuração padrão, a Stripe tenta reconciliar automaticamente a transferência bancária usando informações como o código de referência da transferência ou o valor transferido.

Você mesmo pode desativar a reconciliação automática e reconciliar manualmente pagamentos e faturas. É possível sobrepor o comportamento de reconciliação automática por cliente, definindo o modo de reconciliação como manual.

Configurar a Stripe
Lado do servidor

Primeiro, você precisa de uma conta Stripe. Cadastre-se agora.

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

Command Line
Ruby
Python
PHP
Java
Node
Go
.NET
No results
# Available as a gem
sudo gem install stripe
Gemfile
Ruby
Python
PHP
Java
Node
Go
.NET
No results
# If you use bundler, you can add this line to your Gemfile
gem 'stripe'

Crie ou recupere um Customer
Lado do servidor

É necessário associar um objeto Customer para reconciliar o pagamento de cada transferência bancária. Se você já tem um objeto Customer, ignore esta etapa. Caso contrário, crie um objeto Customer.

Command Line
cURL
Stripe CLI
Ruby
Python
PHP
Java
Node
Go
.NET
No results
curl -X POST https://api.stripe.com/v1/customers \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:"

Criar um PaymentIntent
Lado do servidor

Um PaymentIntent é um objeto que representa sua intenção de coletar o pagamento de um cliente, acompanhando todas as etapas do ciclo de vida do processo de pagamento. Crie um PaymentIntent no servidor, especificando o valor e a moeda que você deseja receber. Você também deve preencher o parâmetro customer da solicitação de criação de PaymentIntent. Sem esse cliente, as transferências bancárias não estão disponíveis no PaymentIntents.

Antes de criar um Payment Intent, ative Transferência bancária na página de configurações de formas de pagamento do Dashboard.

Observação

Com as formas de pagamento dinâmicas, a Stripe gerencia o retorno de formas de pagamento qualificadas com base em fatores como valor, moeda e fluxo de pagamento da transação.

Command Line
cURL
Stripe CLI
Ruby
Python
PHP
Java
Node
Go
.NET
No results
curl https://api.stripe.com/v1/payment_intents \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -d amount=1099 \
  -d customer=
{{CUSTOMER_ID}}
 \
  -d currency=usd \
  -d "automatic_payment_methods[enabled]"=true

Na versão mais recente da API, especificar o parâmetro automatic_payment_methods é opcional porque a Stripe habilita sua funcionalidade por padrão.

Se o cliente já tiver um saldo alto o suficiente para cobrir o valor do pagamento, o PaymentIntent é efetivado imediatamente com um status de succeeded. Os clientes podem acumular um saldo quando acidentalmente pagam a mais por uma transação, o que é comum em transferências bancárias. Você deverá reconciliar os saldos do cliente dentro de um determinado período com base na sua localização.

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.

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.

Na confirmação, a Stripe automaticamente abre um modal para exibir os detalhes da transferência bancária para o seu cliente.

Enviar 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;
  }
});

Confirme se o PaymentIntent foi bem-sucedido

O status do PaymentIntent permanece requires_action até o recebimento dos fundos na conta bancária. Quando os fundos ficam disponíveis, o status do PaymentIntent muda de requires_action para succeeded.

O endpoint de webhook precisa estar configurado para começar a receber o evento payment_intent.partially_funded. Quando o PaymentIntent é parcialmente financiado, o status continua sendo requires_action.

Você pode adicionar um webhook no Dashboard.

Como alternativa, use a API Webhook Endpoints para começar a receber o evento payment_intent.partially_funded.

Cuidado

O Stripe CLI não aceita o acionamento de eventos da versão beta API, como payment_intent.partially_funded.

Os eventos a seguir são enviados durante o fluxo de fundos do pagamento quando o status do PaymentIntent é atualizado.

EventoDescriçãoPróximas etapas
payment_intent.requires_actionEnviado durante a confirmação quando o saldo do cliente é insuficiente para reconciliar o PaymentIntent. O status do PaymentIntent muda para requires_action.Oriente o cliente a enviar uma transferência bancária com o valor de amount_remaining.
payment_intent.partially_fundedO cliente enviou uma transferência bancária que foi aplicada ao PaymentIntent, mas não foi suficiente para finalizar o pagamento. Isso pode ocorrer quando o cliente transfere um valor insuficiente (por engano ou dedução de tarifas pelo banco) ou quando um saldo remanescente do cliente é aplicado a esse PaymentIntent. PaymentIntents com fundos parciais não são refletidos no saldo da conta até que o pagamento seja finalizado.Oriente o cliente a enviar outra transferência bancária com o novo amount_remaining para finalizar o pagamento. Se quiser concluir o pagamento com os fundos parciais, atualize amount e confirme o PaymentIntent novamente.
payment_intent.succeededO pagamento do cliente foi confirmado.Execute o pedido de mercadorias ou serviços do cliente.

Cuidado

Quando você altera o valor de um PaymentIntent parcialmente financiado, os fundos são devolvidos ao saldo do cliente. Se houver outros PaymentIntents abertos, a Stripe os financia automaticamente. Se houver outros PaymentIntents abertos, a Stripe os financia automaticamente. Se o cliente estiver configurado para reconciliação manual, você precisará aplicar os fundos novamente.

Recomendamos usar webhooks para confirmar que a cobrança foi bem-sucedida e notificar o cliente de que o pagamento está concluído.

Exemplo de código

Ruby
Python
PHP
Java
Node
Go
.NET
No results
require 'json'

# Using Sinatra
post '/webhook' do
  payload = request.body.read
  event = nil

  begin
    event = Stripe::Event.construct_from(
      JSON.parse(payload, symbolize_names: true)

Ver pagamentos pendentes no Dashboard

Para ver todos os PaymentIntents de transferências bancárias pendentes no Dashboard, aplique o filtro Aguardando fundos ao Status.

Teste sua integração

Teste a integração simulando o recebimento de uma transferência bancária na API, no Dashboard ou usando uma versão beta da Stripe CLI.

To simulate a bank transfer using the Dashboard in a sandbox, go to the customer’s page in the Dashboard. Under Payment methods, click Add and select Fund cash balance (test only).

Gerenciar problemas temporários de disponibilidade

Os seguintes códigos de erro indicam problemas temporários com a disponibilidade da forma de pagamento:

CódigoDescriçãoTratamento
payment_method_rate_limit_exceededForam realizadas solicitações em excesso em sequência para esta forma de pagamento, que tem limites mais rígidos do que as limitações de fluxo em toda a API.Esses erros podem persistir para várias solicitações de API quando muitos dos seus clientes tentam usar a mesma forma de pagamento, como durante uma venda em andamento no seu site. Nesse caso, peça para seus clientes escolherem uma forma de pagamento diferente.

Cuidado

Se você prevê um uso intenso em geral ou devido a um evento que está por vir, entre em contato conosco assim que tiver conhecimento.

Esta página foi útil?
SimNão