Botão de solicitação de pagamento
Cuidado
O Payment Request Button Element exibe dinamicamente opções de carteira durante o checkout, oferecendo uma integração única para Apple Pay, Google Pay e Link. Alternativamente, você pode usar o Express Checkout Element para oferecer vários botões de pagamento com um clique aos seus clientes. Compare o Express Checkout Element e o botão Solicitar pagamento.
Os clientes veem o Apple Pay ou o Google Pay se os habilitarem no dispositivo e dependendo do navegador utilizado. Se o Link aparecer, é possível que:
- Eles não tenham Apple Pay ou Google Pay habilitados no dispositivo.
- Usem o Chrome com sessões ativas e autenticadas do Link.
Pré-requisitos
Antes de começar, você precisa:
- Revise os requisitos para cada tipo de botão de pagamento:
- O Apple Pay exige macOS 10.12.1+ ou iOS 10.1+.
- Dispositivos compatíveis aceitam automaticamente o Google Pay.
- Registre e verifique seu domínio em modo de teste e de produção.
- Adicionar uma forma de pagamento ao seu navegador. Por exemplo, salve um cartão no Chrome, adicione um cartão à sua conta do Google Pay ou adicione um cartão ao Wallet do Safari.
- Enviar seu aplicativo por HTTPS. É obrigatório tanto em desenvolvimento quanto em produção. Sugerimos um serviço como ngrok para começar.
Configurar o Stripe Elements
Observação
A demonstração da CodeSandbox permite testar o React Stripe.js sem criar um novo projeto.
Adicione Stripe.js e Elements à sua página
Para usar componentes do Elements, encapsule o componente da página de checkout em um provedor do Elements. Chame loadStripe
com sua chave publicável e passe a Promise
recebida para o provedor Elements
.
import React from 'react'; import ReactDOM from 'react-dom'; import {Elements} from '@stripe/react-stripe-js'; import {loadStripe} from '@stripe/stripe-js'; import CheckoutForm from './CheckoutForm'; // Make sure to call `loadStripe` outside of a component's render to avoid // recreating the `Stripe` object on every render. const stripePromise = loadStripe(
); function App() { return ( <Elements stripe={stripePromise}> <CheckoutForm /> </Elements> ); }; ReactDOM.render(<App />, document.getElementById('root'));'pk_test_TYooMQauvdEDq54NiTphI7jx'
Crie uma instância paymentRequestDo lado do cliente
No seu componente de formulário de checkout, crie uma instância de stripe.paymentRequest com todas as opções obrigatórias.
import React, {useState, useEffect} from 'react'; import {PaymentRequestButtonElement, useStripe} from '@stripe/react-stripe-js'; const CheckoutForm = () => { const stripe = useStripe(); const [paymentRequest, setPaymentRequest] = useState(null); useEffect(() => { if (stripe) { const pr = stripe.paymentRequest({ country: 'US', currency: 'usd', total: { label: 'Demo total', amount: 1099, }, requestPayerName: true, requestPayerEmail: true, }); } }, [stripe]); // Use a traditional checkout form. return 'Insert your form or button component here.'; }
Observação
Use o parâmetro requestPayerName
para obter o endereço de cobrança do pagador para o Apple Pay. O endereço de cobrança pode ser usado para verificar o endereço e bloquear fraudes. Todas as outras formas de pagamento coletam automaticamente o endereço de cobrança, quando disponível.
Processar o Element botão de solicitação de pagamentoDo lado do cliente
Verifique se o cliente tem uma forma de pagamento ativa utilizando canMakePayment. Se tiver, renderize o <PaymentRequestButtonElement>
. Se não tiver, não é possível renderizar o elemento. Neste caso, sugerimos que você mostre um formulário de checkout tradicional.
import React, {useState, useEffect} from 'react'; import {PaymentRequestButtonElement, useStripe} from '@stripe/react-stripe-js'; const CheckoutForm = () => { const stripe = useStripe(); const [paymentRequest, setPaymentRequest] = useState(null); useEffect(() => { if (stripe) { const pr = stripe.paymentRequest({ country: 'US', currency: 'usd', total: { label: 'Demo total', amount: 1099, }, requestPayerName: true, requestPayerEmail: true, }); // Check the availability of the Payment Request API. pr.canMakePayment().then(result => { if (result) { setPaymentRequest(pr); } }); } }, [stripe]); if (paymentRequest) { return <PaymentRequestButtonElement options={{paymentRequest}} /> } // Use a traditional checkout form. return 'Insert your form or button component here.'; }
Crie um PaymentIntentLado 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.
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.
O PaymentIntent retornado contém um segredo do cliente, que você usa para concluir o processo de pagamento com segurança em vez de passar todo o objeto PaymentIntent. Envie o segredo do cliente de volta para o cliente utilizá-lo na próxima etapa.
Finalizar o pagamentoDo lado do cliente
Escute o evento paymentmethod
para receber um objeto PaymentMethod. Passe o ID do PaymentMethod e o segredo do cliente do PaymentIntent para stripe.confirmCardPayment para concluir o pagamento.
paymentRequest.on('paymentmethod', async (ev) => { // Confirm the PaymentIntent without handling potential next actions (yet). const {paymentIntent, error: confirmError} = await stripe.confirmCardPayment( clientSecret, {payment_method: ev.paymentMethod.id}, {handleActions: false} ); if (confirmError) { // Report to the browser that the payment failed, prompting it to // re-show the payment interface, or show an error message and close // the payment interface. ev.complete('fail'); } else { // Report to the browser that the confirmation was successful, prompting // it to close the browser payment method collection interface. ev.complete('success'); // Check if the PaymentIntent requires any actions and, if so, let Stripe.js // handle the flow. If using an API version older than "2019-02-11" // instead check for: `paymentIntent.status === "requires_source_action"`. if (paymentIntent.status === "requires_action") { // Let Stripe.js handle the rest of the payment flow. const {error} = await stripe.confirmCardPayment(clientSecret); if (error) { // The payment failed -- ask your customer for a new payment method. } else { // The payment has succeeded -- show a success message to your customer. } } else { // The payment has succeeded -- show a success message to your customer. } } });
Cuidado
Em alguns navegadores, a interface de pagamento pode ser ignorada pelo cliente após a autorização do pagamento. Isso significa que você pode receber um evento cancel no seu objeto PaymentRequest após receber um evento token
ou paymentmethod
. Se usar evento cancel
como hook para cancelar o pedido do cliente, não deixe de também reembolsar o pagamento que acabou de criar.
Teste sua integração
Para testar sua integração, você precisa usar HTTPS e um navegador compatível. Se você usar o Element paymentRequestButton
em um iframe, o iframe precisará ter o atributo allow definido como “payment*”.
Além disso, cada forma de pagamento e navegador tem requisitos específicos:
Coletar dados de envio
Para coletar dados de envio, comece incluindo requestShipping: true
ao criar a solicitação de pagamento.
Você também pode fornecer uma matriz de shippingOptions
nesse momento, se as suas opções de envio não dependerem do endereço do cliente.
const paymentRequest = stripe.paymentRequest({ country: 'US', currency: 'usd', total: { label: 'Demo total', amount: 1099, }, requestShipping: true, // `shippingOptions` is optional at this point: shippingOptions: [ // The first shipping option in this list appears as the default // option in the browser payment interface. { id: 'free-shipping', label: 'Free shipping', detail: 'Arrives in 5 to 7 days', amount: 0, }, ], });
Em seguida, ouça o evento shippingaddresschange
para detectar quando um cliente seleciona um endereço de entrega. Use o endereço para obter opções de envio válidas do seu servidor, atualizar o total ou executar outra lógica comercial. Os dados de endereço no evento shippingaddresschange
podem ser anonimizados pelo navegador para não revelar informações confidenciais que não são necessárias para o cálculo do custo de envio.
O cliente deve informar shippingOptions
válidas neste momento para prosseguir no fluxo.
paymentRequest.on('shippingaddresschange', async (ev) => { if (ev.shippingAddress.country !== 'US') { ev.updateWith({status: 'invalid_shipping_address'}); } else { // Perform server-side request to fetch shipping options const response = await fetch('/calculateShipping', { data: JSON.stringify({ shippingAddress: ev.shippingAddress }) }); const result = await response.json(); ev.updateWith({ status: 'success', shippingOptions: result.supportedShippingOptions, }); } });
Exibir itens de linha
Use displayItems
para exibir objetos PaymentItem
e mostrar o detalhamento de preços na interface de pagamento do navegador.
const pr = stripe.paymentRequest({ country: 'US', currency: 'usd', total: { label: 'Demo total', amount: 2000, }, displayItems: [ { label: 'Sample item', amount: 1000, }, { label: 'Shipping cost', amount: 1000, } ], });
Personalizar o botão
Use os seguintes parâmetros para personalizar o Element:
const options = { paymentRequest, style: { paymentRequestButton: { type: 'default', // One of 'default', 'book', 'buy', or 'donate' // Defaults to 'default' theme: 'dark', // One of 'dark', 'light', or 'light-outline' // Defaults to 'dark' height: '64px', // Defaults to '40px'. The width is always '100%'. }, } } <PaymentRequestButtonElement options={options} />
Usar seu próprio botão
Se quiser criar seu próprio botão em vez de usar o Element paymentRequestButton
, você pode mostrar o botão personalizado com base no resultado de paymentRequest.canMakePayment(). Em seguida, use paymentRequest.show() para exibir a interface do navegador quando o botão for clicado.
Para criar seu próprio botão, siga as Diretrizes de interface humana do Apple Pay e as Diretrizes de marca do Google Pay.
Usar o botão Solicitar pagamento com o Stripe Connect
No seu fontend, antes de criar a instância
PaymentRequest
, defina a opçãostripeAccount
na instância da Stripe:const stripe = Stripe(
, { apiVersion: "2024-04-10", stripeAccount: 'CONNECTED_STRIPE_ACCOUNT_ID', });'pk_test_TYooMQauvdEDq54NiTphI7jx'Registre todos os domínios onde você pretende exibir o botão de solicitação de pagamento.
Link para o botão Solicitação de pagamento
Quando novos clientes chegam ao seu site, eles podem usar o Link no botão Solicitar pagamento para pagar com seus dados de pagamento salvos. Com o Link, eles não precisam inserir manualmente os dados de pagamento. O Link requer registro de domínio.
Divulgue a Stripe para seus clientes
A Stripe coleta informações sobre interações do cliente com o Elements para fornecer serviços a você, evitar fraudes e melhorar os serviços. Isso inclui o uso de cookies e endereços IP para identificar quais Elements o cliente visualizou durante uma única sessão de checkout. Você é responsável por divulgar e obter todos os direitos e consentimentos necessários para que a Stripe use os dados dessas maneiras. Para saber mais, acesse nossa central de privacidade.