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.

Configure a Stripe
Lado do servidor

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

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'

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ê tiver um objeto Customer existente, ignore essa etapa. Caso contrário, crie um objeto Customer.

Command Line
curl -X POST https://api.stripe.com/v1/customers \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:"

Crie e confirme um PaymentIntent
Lado do servidor

Um PaymentIntent é um objeto que representa sua intenção de receber pagamento de um cliente e acompanha o ciclo de vida do processo de pagamento durante cada etapa. Crie e confirme um PaymentIntent no servidor, especificando o valor e a moeda que você deseja receber. Você também precisa preencher o parâmetro customer da solicitação de criação de PaymentIntent. Sem esse parâmetro, 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 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 \
  --data-urlencode return_url="https://example.com/return_url" \
  -d "payment_method_data[type]"=customer_balance \
  -d confirm=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.

Oriente o cliente a finalizar uma transferência bancária
Lado do cliente

Se o saldo do cliente não for alto o suficiente para cobrir o valor da solicitação, o PaymentIntent mostrará o status requires_action. A resposta tem um campo next_action com o valor de type de display_bank_transfer_instructions. O hash next_action[display_bank_transfer_instructions] contém informações a serem exibidas ao cliente para que ele finalize a transferência bancária. Para assegurar a liquidação de fundos, instrua seus clientes a usar os dados exatamente como foram fornecidos, especialmente o nome e o número da conta, se houver.

Observação

No modo de produção, a Stripe fornece a cada cliente um conjunto único de dados de transferência bancária. Por outro lado, a Stripe oferece dados de transferência bancária inválidos a todos os clientes em ambientes de teste. Ao contrário do modo de produção, esses dados inválidos podem não ser únicos.

CampoDescrição
typeO tipo de transferência bancária que você usa. O tipo deve ser us_bank_transfer nos EUA.
referenceUm código de referência exclusivo para identificar a transferência bancária. Instrua seu cliente a incluir esse código no campo de referência da transferência bancária.
amount_remainingO valor restante que precisa ser transferido para concluir o pagamento. Instrua seu cliente a transferir esse valor. Ele pode ser diferente do valor do PaymentIntent se fundos preexistentes no saldo do cliente tiverem sido aplicados ao PaymentIntent ou se o seu cliente tiver pago a menos.
currencyA moeda para o valor restante.
financial_addressesLista de endereços financeiros para contas bancárias dos EUA. Os tipos incluem aba e swift. Confira os detalhes abaixo.
hosted_instructions_urlUm link para uma página hospedada que orienta seu cliente durante a transferência.

hash de aba

Exemplo de um hash aba:

{
  "aba": {
    "account_number": "111222333444",
    "bank_name": "Wells Fargo Bank, NA",
    "routing_number": "444555666"
  },
  "supported_networks": [
    "ach",
    "domestic_wire_us"
  ],
  "type": "aba"
}
CampoValoresDescrição
typeabaO tipo de endereço financeiro.
supported_networks
  • ach
  • domestic_wire_us
A lista de redes aceitas por este endereço.
aba.account_number111222333444O número da conta ABA.
aba.routing_number444555666O número routing ABA.
aba.bank_nameWells Fargo Bank, NAO nome do banco.

hash de swift

Exemplo de um hash swift:

{
  "swift": {
    "account_number": "111222333444",
    "bank_name": "Wells Fargo Bank, NA",
    "swift_code": "AAAA-BB-CC-123"
  },
  "supported_networks": [
    "swift"
  ],
  "type": "swift"
}
CampoValoresDescrição
typeswiftO tipo de endereço financeiro.
supported_networks
  • swift
A lista de redes aceitas por este endereço.
swift.account_number111222333444O número da conta SWIFT.
swift.swift_codeAAAA-BB-CC-123O código SWIFT.
swift.bank_nameWells Fargo Bank, NAO nome do banco.

Cronograma de liquidação de fundos

Após instruir o cliente a iniciar uma transferência com o banco usando as informações fornecidas por você, pode demorar até 5 dias para a transferência ser concluída. O cronograma de liquidação de fundos depende dos sistemas bancários pelos quais a transferência chegou à Stripe:

  • Transferências ACH chegam entre 1 e 3 dias úteis.
  • As transferências bancárias nacionais (Fedwire) chegam no mesmo dia (dependendo se a transferência é enviada antes do horário limite do banco).
  • Transferências internacionais (SWIFT) chegam entre 1 e 5 dias úteis.

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.

Você precisa configurar seu endpoint webhook para começar a receber o evento payment_intent.partially_funded.

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.

A Stripe envia os eventos a seguir durante o fluxo de financiamento do pagamento quando atualizamos o PaymentIntent.

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 valor de amount_remaining para finalizar o pagamento. Se quiser finalizar o pagamento com os fundos parciais, atualize amount e confirme novamente o PaymentIntent.
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 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

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 a integração

Você pode testar sua integração ao simular a entrada de uma transferência bancária usando o Dashboard ou uma solicitação de HTTP.

Com o Dashboard

Para simular uma transferência bancária usando o Dashboard em uma área restrita, navegue até a página do cliente no Dashboard. Em Formas de pagamento, clique em Adicionar e selecione Financiar saldo em dinheiro (somente teste).

Com a API da Stripe

Você pode simular uma transferência bancária usando uma chamada de API.

Command Line
curl https://api.stripe.com/v1/test_helpers/customers/ic_xxxxxxxxx/fund_cash_balance \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -d amount=1000 \
  -d currency=usd \
  -d reference=REF-4242

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