Criar uma página de pagamentos
Integre Apple Pay e Google Pay com programação adicional.
Personalize todos os componentes com CSS.
Observação
Consulte o perfil da sua plataforma para determinar se a opção Direct Charges ou Destination Charges é recomendada para a sua empresa.
Cobranças de destino
Neste exemplo, a plataforma é um marketplace de aluguel residencial que precisa criar pagamentos para proprietários que alugam suas propriedades. Você também pode usar destination charges em outros aplicativos.
Etapa 1: Crie um PaymentIntent Lado do servidor
curl https://api.stripe.com/v1/payment_intents \ -u "
:" \ -d amount=1099 \ -d currency=usd \ -d "automatic_payment_methods[enabled]"=truesk_test_4eC39HqLyjWDarjtT1zdp7dc
Na versão mais recente da API, especificar o parâmetro automatic_payment_methods
é opcional porque a Stripe habilita sua funcionalidade por padrão.
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.
Crie um PaymentIntent
no seu servidor com valor e moeda. Sempre defina o valor a ser cobrado no servidor, que é um ambiente seguro, e não no cliente. Dessa forma, você evita que clientes mal-intencionados escolham os próprios preços.
curl https://api.stripe.com/v1/payment_intents \ -u
: \ -d amount=1000 \ -d currency="usd" \ -d "automatic_payment_methods[enabled]"=true \ -d application_fee_amount="123" \ -d "transfer_data[destination]"=sk_test_4eC39HqLyjWDarjtT1zdp7dc{{CONNECTED_STRIPE_ACCOUNT_ID}}
Em nosso exemplo para aluguel residencial, queremos criar uma empresa em que os clientes pagam o aluguel em nossa plataforma, e nós repassamos o aluguel aos locatários. Para configurar esta empresa:
- Indique que o aluguel é uma cobrança de destino, com
transfer_data[destination]
. - Especifique em
application_fee_amount
o valor que será pago à plataforma.
Ao cobrar um aluguel, a Stripe transfere o valor total para o saldo em aberto da conta conectada (transfer_data[destination]
). Em seguida, a Stripe transfere a tarifa (application_fee_amount
) para a conta da plataforma (uma participação na receita, pela intermediação do aluguel). Por fim, são deduzidas as tarifas da Stripe do valor da tarifa da plataforma. Veja esse fluxo ilustrado abaixo:
Observação
Este PaymentIntent cria uma cobrança de destino. Para controlar o cronograma das transferências ou precisar transferir fundos de um único pagamento para mais de uma parte, use cobranças e transferências separadas.
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:
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 })();
Etapa 2: Colete detalhes do cartão Lado do cliente
Você já pode coletar dados de cartão dos clientes com o Stripe Elements. O Elements é um conjunto de componentes de IU pré-integrados para coletar e validar número, código postal e data de validade de cartões.
Um Stripe Element contém um iframe que envia com segurança os dados de pagamento para a Stripe por uma conexão HTTPS. O endereço da página de checkout também deve iniciar com https://, e não http://, para que sua integração funcione.
Você pode testar sua integração sem usar HTTPS. Faça a ativação quando tudo estiver pronto para receber pagamentos em operação.
Configurar o Stripe Elements
O Stripe Elements é disponibilizado automaticamente como recurso do script Stripe.js, que deve ser inserido em sua página de checkout, no head
de seu arquivo HTML. Sempre carregue o Stripe.js diretamente de js.stripe.com para manter a conformidade com PCI. Não insira o script em um pacote nem hospede sua própria cópia.
<head> <title>Checkout</title> <script src="https://js.stripe.com/v3/"></script> </head>
Crie uma instância do Elements com o seguinte JavaScript em sua página de checkout:
// Set your publishable key: remember to change this to your live publishable key in production // See your keys here: https://dashboard.stripe.com/apikeys var stripe = Stripe(
); var elements = stripe.elements();'pk_test_TYooMQauvdEDq54NiTphI7jx'
Adicione o Elements à sua página de pagamentos
O Elements precisa de um lugar específico no formulário de pagamento. Crie nós de DOM vazios (contêineres) com IDs individuais no formulário de pagamento e envie os IDs para o Elements.
<form id="payment-form"> <div id="card-element"> <!-- Elements will create input elements here --> </div> <!-- We'll put the error messages in this element --> <div id="card-errors" role="alert"></div> <button id="submit">Pay</button> </form>
Quando o formulário acima for carregado, crie uma instância de um elemento e monte-a no contêiner do elemento:
// Set up Stripe.js and Elements to use in checkout form var elements = stripe.elements(); var style = { base: { color: "#32325d", } }; var card = elements.create("card", { style: style }); card.mount("#card-element");
O Element card
simplifica o formulário e minimiza o número de campos necessários, inserindo um campo único e flexível que coleta com segurança todos os dados de cartão e faturamento. Você também pode combinar os elementos cardNumber
, cardExpiry
e cardCvc
para montar um formulário flexível com vários campos para os dados de cartão.
Observação
Sempre colete um código postal para aumentar as taxas de aceitação de cartão e reduzir fraudes.
O Card Element de uma única linha coleta e envia automaticamente o código postal do cliente à Stripe. Se você criar um formulário de pagamento com Elements divididos (Card Number, Expiry e CVC), adicione um campo de entrada separado para o código postal do cliente.
Veja a lista completa de tipos de elementos compatíveis na documentação de referência do Stripe.js.
O Elements valida as inserções do usuário conforme são digitadas. Para ajudar os clientes a reconhecer erros, escute eventos de change
no Element card
e exiba os alertas:
card.on('change', ({error}) => { let displayError = document.getElementById('card-errors'); if (error) { displayError.textContent = error.message; } else { displayError.textContent = ''; } });
A validação de código postal depende do país onde acontece o faturamento do cliente. Use nossos cartões internacionais de teste para testar outros formatos de código postal.
Etapa 3: Envie o pagamento à Stripe Lado do cliente
Em vez de enviar todo o objeto PaymentIntent ao cliente, use o segredo do cliente de Step 1. Isso é diferente das suas chaves de API que autenticam as solicitações da API da Stripe.
O segredo do cliente deve ser administrado com cuidado, pois é possível finalizar a cobrança com ele. Não armazene, insira em URL nem exponha o segredo para ninguém, exceto para o próprio cliente.
Para finalizar o pagamento quando o usuário clicar, recupere o segredo do cliente do PaymentIntent criado em Step 1 e chame stripe.confirmCardPayment com o segredo do cliente.
Passe outros detalhes do faturamento, como nome e endereço do titular do cartão, para o hash billing_details
. O elemento card
envia automaticamente o código postal do cliente. No entanto, para combinar os elementos cardNumber
, cardCvc
e cardExpiry
, é preciso enviar o código postal para billing_details[address][postal_code]
.
var form = document.getElementById('payment-form'); form.addEventListener('submit', function(ev) { ev.preventDefault(); stripe.confirmCardPayment(clientSecret, { payment_method: { card: card, billing_details: { name: 'Jenny Rosen' } } }).then(function(result) { if (result.error) { // Show error to your customer (for example, insufficient funds) console.log(result.error.message); } else { // The payment has been processed! if (result.paymentIntent.status === 'succeeded') { // Show a success message to your customer // There's a risk of the customer closing the window before callback // execution. Set up a webhook or plugin to listen for the // payment_intent.succeeded event that handles any business critical // post-payment actions. } } }); });
Observação
stripe.confirmCardPayment
pode levar vários segundos para finalizar. Durante esse período, impeça que o formulário seja reenviado e mostre um indicador de espera, como uma ampulheta. Se receber um erro, mostre-o ao cliente, reative o formulário e oculte o indicador de espera.
Se o cliente precisar autenticar o cartão, Stripe.js orienta o processo com um modal. Para ver um exemplo desse modal, use o cartão de teste número com qualquer CVC, data de validade futura e código postal na demonstração da parte superior da página.
Quando o pagamento é finalizado, o valor da propriedade status
do PaymentIntent indica que a transação foi bem-sucedida. Verifique o status de um PaymentIntent no Dashboard ou inspecione a propriedade do status no objeto. Se o pagamento falhar, inspecione o error
para determinar a causa.
Etapa 4: Execução Lado do servidor
Após a conclusão do pagamento, é preciso gerenciar qualquer execução necessária. Uma empresa de aluguel residencial que exige pagamento antecipado, por exemplo, conectaria o proprietário ao locatário após um pagamento realizado.
Configure um endpoint de webhook (para eventos de sua conta) no Dashboard.
Em seguida, crie um endpoint de HTTP no seu servidor para monitorar pagamentos concluídos para habilitar seus vendedores ou prestadores de serviços a processar compras. Certifique-se de substituir a chave secreta do endpoint (whsec_...
) no exemplo com sua chave.
# Using Sinatra. require 'sinatra' require 'stripe' set :port, 4242 # Set your secret key. Remember to switch to your live secret key in production. # See your keys here: https://dashboard.stripe.com/apikeys Stripe.api_key =
# If you are testing your webhook locally with the Stripe CLI you # can find the endpoint's secret by running `stripe listen` # Otherwise, find your endpoint's secret in your webhook settings in # the Developer Dashboard endpoint_secret = 'whsec_...' post '/webhook' do payload = request.body.read sig_header = request.env['HTTP_STRIPE_SIGNATURE'] event = nil # Verify webhook signature and extract the event. # See https://stripe.com/docs/webhooks#verify-events for more information. begin event = Stripe::Webhook.construct_event( payload, sig_header, endpoint_secret ) rescue JSON::ParserError => e # Invalid payload. status 400 return rescue Stripe::SignatureVerificationError => e # Invalid Signature. status 400 return end if event['type'] == 'payment_intent.succeeded' payment_intent = event['data']['object'] handle_successful_payment_intent(payment_intent) end status 200 end def handle_successful_payment_intent(payment_intent) # Fulfill the purchase puts payment_intent.to_s end'sk_test_4eC39HqLyjWDarjtT1zdp7dc'
Saiba mais no nosso guia de processamento para pagamentos.
Testar webhooks localmente
Use a Stripe CLI para testar webhooks localmente.
Se você ainda não instalou a Stripe CLI em sua máquina, instale-a agora.
Para fazer login, execute
stripe login
na linha de comando e siga as instruções.Por fim, para permitir que seu host local receba um evento simulado em sua conta conectada, execute
stripe listen --forward-to localhost:{PORT}/webhook
em uma janela do terminal e executestripe trigger --stripe-account={{CONNECTED_STRIPE_ACCOUNT_ID}} payment_intent.succeeded
(ou acione qualquer outro evento aceito) em outro.
Etapa 5: Contestações
Como comerciante de liquidação das cobranças, sua plataforma é responsável pelas contestações. Leia com atenção as práticas recomendadas para responder a contestações.
Ativar formas de pagamento
Stripe enables certain payment methods for your connected accounts by default. You can change these defaults at any time in your Stripe Dashboard.
Antes da exibição das formas de pagamento, 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. Priorizamos as que aumentam a conversão e são mais relevantes para a moeda e a localização do cliente. As formas de pagamento de menor prioridade são ocultas em um menu de estouro.