# Salvar a forma de pagamento de um cliente sem fazer pagamento Saiba como salvar uma forma de pagamento e cobrá-la mais tarde. # API de sessões de checkout > This is a API de sessões de checkout for when payment-ui is embedded-components. View the full page at https://docs.stripe.com/payments/save-and-reuse?payment-ui=embedded-components. A API [Checkout Sessions em `setup` mode](https://docs.stripe.com/api/checkout/sessions/create.md#create_checkout_session-mode) permite que você salve os detalhes de pagamento de um cliente sem um pagamento inicial. Isso é útil se você quiser fazer onboarding dos clientes agora, configurá-los para pagamentos e cobrá-los usando a API Payment Intents no futuro, quando estiverem offline. Use esta integração para configurar pagamentos recorrentes ou criar pagamentos avulsos de valores a serem definidos mais tarde, talvez depois de o cliente receber seu serviço. > #### Transações com cartão presente > > As transações com cartão presente, como [, as que recolhem os dados do cartão por meio do Stripe Terminal](https://docs.stripe.com/terminal/features/saving-payment-details/save-directly.md), usam um processo diferente para salvar as formas de pagamento. ## Conformidade Você é responsável por cumprir todas as leis, regulamentos e regras da bandeira em vigor ao salvar os dados de pagamento de um cliente. Esses requisitos geralmente se aplicam quando você quer salvar a forma de pagamento do cliente para uso futuro, como exibir a forma de pagamento de um cliente para ele no fluxo de checkout para uma compra futura ou cobrá-lo quando não estiver usando seu site ou aplicativo. Adicione termos ao seu site ou aplicativo que definam como você planeja salvar os dados da forma de pagamento e permitir que os clientes aceitem. Quando salva uma forma de pagamento, você só pode usá-la para o uso específico incluído em seus termos. Para cobrar uma forma de pagamento quando o cliente está offline e salvá-la como opção para compras futuras, não se esqueça de recolher o consentimento do cliente para esse uso específico. Por exemplo, inclua a caixa de seleção “Salvar minha forma de pagamento para uso futuro” para recolher o consentimento. Para cobrar um cliente quando ele estiver off-line, certifique-se de que seus termos incluam o seguinte: - A concordância do cliente para que você inicie um pagamento ou uma série de pagamentos em nome dele para transações específicas. - O momento e a frequência previstos para os pagamentos (por exemplo, se são cobranças de parcelas agendadas, pagamentos de assinatura ou recargas não agendadas). - Como você determina o valor do pagamento. - Sua política de cancelamento, se a forma de pagamento for usada em um serviço de assinatura. Não se esqueça de manter um registro por escrito da concordância do cliente com esses termos. > Se você precisar usar a confirmação manual do lado do servidor ou se sua integração exigir a apresentação de formas de pagamento separadamente, consulte nosso [guia alternativo ](https://docs.stripe.com/payments/save-and-reuse-cards-only.md) . ## Configurar a Stripe [Lado do servidor] Primeiro, [crie uma conta Stripe](https://dashboard.stripe.com/register) ou [entre](https://dashboard.stripe.com/login). Use nossas bibliotecas oficiais para acessar a API da Stripe no seu aplicativo: #### Ruby ```bash # Available as a gem sudo gem install stripe ``` ```ruby # If you use bundler, you can add this line to your Gemfile gem 'stripe' ``` ## Criar um cliente [Lado do servidor] Para configurar uma forma de pagamento para pagamentos futuros, você deve associá-la a um objeto que represente seu cliente. Quando o cliente criar uma conta ou tiver sua primeira transação com sua empresa, crie um objeto [Account](https://docs.stripe.com/api/v2/core/accounts/create.md) configurado para o cliente usando a API Accounts v2 ou um objeto [Customer](https://docs.stripe.com/api/customers/create.md) usando a API Customers. > #### Use a API Accounts v2 para representar clientes > > A API Accounts v2 está geralmente disponível para usuários do Connect e em prévia pública para outros usuários da Stripe. Se faz parte da prévia de Accounts v2, é necessário [especificar uma versão de prévia](https://docs.stripe.com/api-v2-overview.md#sdk-and-api-versioning) no seu código. > > Para solicitar acesso à prévia de Accounts v2, > > For most use cases, we recommend [modeling your customers as customer-configured Account objects](https://docs.stripe.com/accounts-v2/use-accounts-as-customers.md) instead of using [Customer](https://docs.stripe.com/api/customers.md) objects. #### Accounts v2 ```curl curl -X POST https://api.stripe.com/v2/core/accounts \ -H "Authorization: Bearer <>" \ -H "Stripe-Version: 2026-04-22.preview" ``` #### Clientes v1 ```curl curl -X POST https://api.stripe.com/v1/customers \ -u "<>:" ``` ## Usar o modo de configuração [Lado do servidor] Crie uma sessão de Checkout com [mode=setup](https://docs.stripe.com/api/checkout/sessions/create.md#create_checkout_session-mode). ```curl curl https://api.stripe.com/v1/checkout/sessions \ -u "<>:" \ -d mode=setup \ -d ui_mode=elements \ -d currency=usd ``` ## Anexe a forma de pagamento a um cliente [Lado do servidor] Se você não criou a Checkout Session com um cliente existente, use o ID do *PaymentMethod* (PaymentMethods represent your customer's payment instruments, used with the Payment Intents or Setup Intents APIs) para [attach](https://docs.stripe.com/api/payment_methods/attach.md) a forma de pagamento para um cliente. Caso contrário, a forma de pagamento será automaticamente vinculada ao cliente que você forneceu ao criar a Checkout Session. #### Accounts v2 ```curl curl https://api.stripe.com/v1/payment_methods/{{PAYMENTMETHOD_ID}}/attach \ -u "<>:" \ -d "customer_account={{CUSTOMERACCOUNT_ID}}" ``` #### Clientes v1 ```curl curl https://api.stripe.com/v1/payment_methods/{{PAYMENTMETHOD_ID}}/attach \ -u "<>:" \ -d "customer={{CUSTOMER_ID}}" ``` ## Recuperar a forma de pagamento [Lado do servidor] Depois que um cliente concluir com êxito sua sessão de Checkout, trate o Webhook [checkout.session.completed](https://docs.stripe.com/api/events/types.md#event_types-checkout.session.completed). Recupere o objeto Session no Webhook e faça o seguinte: - Obtenha o valor da chave [setup_intent](https://docs.stripe.com/api/checkout/sessions/object.md#checkout_session_object-setup_intent), que é a ID do SetupIntent criada durante a Checkout Session. - Use a ID SetupIntent para [recuperar](https://docs.stripe.com/api/setup_intents/retrieve.md) o objeto SetupIntent. O objeto retornado contém um [payment_method](https://docs.stripe.com/api/setup_intents/object.md#setup_intent_object-payment_method) ID que você pode anexar a um cliente na próxima etapa. Saiba mais sobre [configuração de Webhooks](https://docs.stripe.com/webhooks.md). ## Cobrar a forma de pagamento mais tarde [Lado do servidor] Depois de anexar o PaymentMethod a um cliente, você pode fazer um pagamento *off-session* (A payment is described as off-session if it occurs without the direct involvement of the customer, using previously-collected payment information) usando um [PaymentIntent](https://docs.stripe.com/api/payment_intents/create.md#create_payment_intent-payment_method): - Defina [customer_account](https://docs.stripe.com/api/payment_intents/create.md#create_payment_intent-customer_account) como ID da `Account` ou [customer](https://docs.stripe.com/api/payment_intents/create.md#create_payment_intent-customer) como ID do `Customer`, e defina [payment_method](https://docs.stripe.com/api/payment_intents/create.md#create_payment_intent-payment_method) como o ID do `PaymentMethod`. - Defina [off_session](https://docs.stripe.com/api/payment_intents/confirm.md#confirm_payment_intent-off_session) para `true` para indicar que o cliente não está em seu fluxo de checkout durante uma tentativa de pagamento e não pode executar uma solicitação de autenticação feita por um parceiro, como um emissor de cartão, banco ou outra instituição de pagamento. Se, durante o seu fluxo de checkout, um parceiro solicitar autenticação, o Stripe Authentication solicita isenções usando informações do cliente de uma transação anterior *on-session* (A payment is described as on-session if it occurs while the customer is actively in your checkout flow and able to authenticate the payment method). Se as condições para isenção não forem atendidas, o PaymentIntent poderá resultar em um erro. - Defina o valor do PaymentIntent’s [confirma](https://docs.stripe.com/api/payment_intents/create.md#create_payment_intent-confirm) a propriedade do PaymentIntent como `true`, o que faz com que a confirmação ocorra imediatamente quando você cria o PaymentIntent. #### Accounts v2 ```curl curl https://api.stripe.com/v1/payment_intents \ -u "<>:" \ -d amount=1099 \ -d currency=usd \ -d "customer_account={{CUSTOMERACCOUNT_ID}}" \ -d "payment_method={{PAYMENTMETHOD_ID}}" \ -d off_session=true \ -d confirm=true ``` #### Clientes v1 ```curl curl https://api.stripe.com/v1/payment_intents \ -u "<>:" \ -d amount=1099 \ -d currency=usd \ -d "customer={{CUSTOMER_ID}}" \ -d "payment_method={{PAYMENTMETHOD_ID}}" \ -d off_session=true \ -d confirm=true ``` Se uma tentativa de pagamento falhar, a solicitação também falhará com um código de status HTTP 402 e o status do PaymentIntent será *requires\_payment\_method*. Notifique o cliente para retornar ao seu aplicativo (por exemplo, enviando um e-mail ou uma notificação no aplicativo) e direcione o cliente para uma nova Checkout Session para selecionar outra forma de pagamento. #### Accounts v2 ```curl curl https://api.stripe.com/v1/checkout/sessions \ -u "<>:" \ -d "customer_account={{CUSTOMERACCOUNT_ID}}" \ -d "line_items[0][price_data][currency]=usd" \ -d "line_items[0][price_data][product_data][name]=T-shirt" \ -d "line_items[0][price_data][unit_amount]=1099" \ -d "line_items[0][quantity]=1" \ -d mode=payment \ -d ui_mode=elements \ --data-urlencode "return_url=https://example.com/return" ``` #### Clientes v1 ```curl curl https://api.stripe.com/v1/checkout/sessions \ -u "<>:" \ -d "customer={{CUSTOMER_ID}}" \ -d "line_items[0][price_data][currency]=usd" \ -d "line_items[0][price_data][product_data][name]=T-shirt" \ -d "line_items[0][price_data][unit_amount]=1099" \ -d "line_items[0][quantity]=1" \ -d mode=payment \ -d ui_mode=elements \ --data-urlencode "return_url=https://example.com/return" ``` # API Setup Intents > This is a API Setup Intents for when payment-ui is elements. View the full page at https://docs.stripe.com/payments/save-and-reuse?payment-ui=elements. A [API Setup Intents](https://docs.stripe.com/api/setup_intents.md) salva os dados de pagamento do cliente sem um pagamento inicial. É uma função útil para integrar um cliente agora e deixar tudo configurado para pagamentos futuros com o cliente fora de sessão. Use esta integração para configurar pagamentos recorrentes ou criar pagamentos avulsos de valores a serem definidos mais tarde, talvez depois de o cliente receber seu serviço. > #### Transações com apresentação de cartão > > As transações com apresentação do cartão, como a coleta de dados do cartão usando o Stripe Terminal, usam um processo diferente para salvar a forma de pagamento. Para obter mais informações, consulte [a documentação do Terminal](https://docs.stripe.com/terminal/features/saving-payment-details/save-directly.md). ## Conformidade Você é responsável por cumprir todas as leis, regulamentos e regras de rede aplicáveis ao salvar os dados de pagamento de um cliente. Esses requisitos geralmente se aplicam quando você quer salvar a forma de pagamento do cliente para uso futuro, como exibir a forma de pagamento de um cliente para ele no fluxo de checkout para uma compra futura ou cobrá-lo quando não estiver usando seu site ou aplicativo. Adicione termos ao seu site ou aplicativo que definam como você planeja salvar os dados da forma de pagamento e permitir que os clientes aceitem. Quando salva uma forma de pagamento, você só pode usá-la para o uso específico incluído em seus termos. Para cobrar uma forma de pagamento quando o cliente está offline e salvá-la como opção para compras futuras, não se esqueça de recolher o consentimento do cliente para esse uso específico. Por exemplo, inclua a caixa de seleção “Salvar minha forma de pagamento para uso futuro” para coletar consentimento. Para cobrar os clientes quando eles estiverem offline, certifique-se de que seus termos incluam o seguinte: - A concordância do cliente para que você inicie um pagamento ou uma série de pagamentos em nome dele para transações específicas. - O momento e a frequência previstos para os pagamentos (por exemplo, se são cobranças de parcelas agendadas, pagamentos de assinatura ou recargas não agendadas). - Como você determina o valor do pagamento. - Sua política de cancelamento, se a forma de pagamento for usada em um serviço de assinatura. Não se esqueça de manter um registro por escrito da concordância do cliente com esses termos. > Se você precisar usar confirmação manual no lado do servidor, ou se sua integração exigir a apresentação de formas de pagamento separadamente, consulte o nosso [guia alternativo](https://docs.stripe.com/payments/save-and-reuse-cards-only.md). ## Configurar a Stripe [Lado do servidor] Primeiro, [crie uma conta Stripe](https://dashboard.stripe.com/register) ou [entre](https://dashboard.stripe.com/login). Use nossas bibliotecas oficiais para acessar a API da Stripe no seu aplicativo: #### Ruby ```bash # Available as a gem sudo gem install stripe ``` ```ruby # If you use bundler, you can add this line to your Gemfile gem 'stripe' ``` ## Ativar formas de pagamento Veja suas [configurações de formas de pagamento](https://dashboard.stripe.com/settings/payment_methods) e habilite as formas de pagamento que deseja aceitar. Você precisa de pelo menos uma forma de pagamento habilitada para criar um *SetupIntent* (The Setup Intents API lets you build dynamic flows for collecting payment method details for future payments. It tracks the lifecycle of a payment setup flow and can trigger additional authentication steps if required by law or by the payment method). Por padrão, a Stripe habilita cartões e outras formas de pagamento predominantes que podem ajudar você a alcançar mais clientes, mas recomendamos ativar outras formas de pagamento que sejam relevantes para sua empresa e seus clientes. Consulte [Suporte a formas de pagamento](https://docs.stripe.com/payments/payment-methods/payment-method-support.md) para saber mais sobre os produtos e formas de pagamento aceitos, e nossa [página de preços](https://stripe.com/pricing/local-payment-methods) para ver as tarifas. ## Criar um cliente [Lado do servidor] Para configurar uma forma de pagamento para pagamentos futuros, você deve associá-la a um objeto que represente seu cliente. Quando o cliente criar uma conta ou tiver sua primeira transação com sua empresa, crie um objeto [Account](https://docs.stripe.com/api/v2/core/accounts/create.md) configurado para o cliente usando a API Accounts v2 ou um objeto [Customer](https://docs.stripe.com/api/customers/create.md) usando a API Customers. > #### Use a API Accounts v2 para representar clientes > > A API Accounts v2 está geralmente disponível para usuários do Connect e em prévia pública para outros usuários da Stripe. Se faz parte da prévia de Accounts v2, é necessário [especificar uma versão de prévia](https://docs.stripe.com/api-v2-overview.md#sdk-and-api-versioning) no seu código. > > Para solicitar acesso à prévia de Accounts v2, > > For most use cases, we recommend [modeling your customers as customer-configured Account objects](https://docs.stripe.com/accounts-v2/use-accounts-as-customers.md) instead of using [Customer](https://docs.stripe.com/api/customers.md) objects. ```curl curl -X POST https://api.stripe.com/v1/customers \ -u "<>:" ``` ## Criar um SetupIntent [Lado do servidor] > Se quiser renderizar o Payment Element antes de criar um SetupIntent, consulte [Coletar detalhes do pagamento antes de criar um Intent](https://docs.stripe.com/payments/accept-a-payment-deferred.md?type=setup). Um [SetupIntent](https://docs.stripe.com/api/setup_intents.md) é um objeto que representa sua intenção de configurar uma forma de pagamento do cliente para pagamentos futuros. As formas de pagamento mostradas aos clientes durante o processo de checkout também estão incluídas no `SetupIntent`. Você pode permitir que a Stripe extraia automaticamente as formas de pagamento das suas configurações do Dashboard, ou você pode listá-las manualmente. Se sua integração não exige uma opção baseada em código para oferecer formas de pagamento, a Stripe recomenda a opção automática. 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. #### Gerencie formas de pagamento no Dashboard Algumas formas de pagamento não podem ser salvas para pagamentos futuros, e os clientes não as veem como opções na configuração de pagamentos futuros. Para obter mais detalhes sobre como gerenciar formas de pagamento, consulte [Opções de integração de formas de pagamento](https://docs.stripe.com/payments/payment-methods/integration-options.md). Você também pode criar um SetupIntent com `automatic_payment_methods` habilitado, e o SetupIntent é criado usando as formas de pagamento configuradas no Dashboard. Especificar o parâmetro `automatic_payment_methods` é opcional porque a Stripe habilita sua funcionalidade por padrão na versão mais recente da API. Você pode gerenciar formas de pagamento no [Dashboard](https://dashboard.stripe.com/settings/payment_methods). 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. #### Accounts v2 ```curl curl https://api.stripe.com/v1/setup_intents \ -u "<>:" \ -d "customer_account={{CUSTOMERACCOUNT_ID}}" \ -d "automatic_payment_methods[enabled]=true" ``` #### Clientes v1 ```curl curl https://api.stripe.com/v1/setup_intents \ -u "<>:" \ -d "customer={{CUSTOMER_ID}}" \ -d "automatic_payment_methods[enabled]=true" ``` #### Liste manualmente as formas de pagamento Crie um SetupIntent no servidor com uma lista de [formas de pagamento](https://docs.stripe.com/payments/payment-methods/integration-options.md) que você quer aceitar. #### Accounts v2 ```curl curl https://api.stripe.com/v1/setup_intents \ -u "<>:" \ -d "customer_account={{CUSTOMERACCOUNT_ID}}" \ -d "payment_method_types[]=bancontact" \ -d "payment_method_types[]=card" \ -d "payment_method_types[]=ideal" ``` #### Clientes v1 ```curl curl https://api.stripe.com/v1/setup_intents \ -u "<>:" \ -d customer={{CUSTOMER_ID}} \ -d "payment_method_types[]=bancontact" \ -d "payment_method_types[]=card" \ -d "payment_method_types[]=ideal" ``` ### Recuperar o segredo do cliente O SetupIntent inclui um *segredo do cliente* (The client secret is a unique key returned from Stripe as part of a PaymentIntent. This key lets the client access important fields from the PaymentIntent (status, amount, currency) while hiding sensitive ones (metadata, customer)) 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. #### Aplicativo de página única 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: #### Ruby ```ruby get '/secret' do intent = # ... Create or retrieve the SetupIntent {client_secret: intent.client_secret}.to_json end ``` Em seguida, obtenha o segredo do cliente com JavaScript no lado do cliente: ```javascript (async () => { const response = await fetch('/secret'); const {client_secret: clientSecret} = await response.json(); // Render the form using the clientSecret })(); ``` #### Renderização do lado do servidor Passe o segredo do cliente do servidor ao cliente. Essa abordagem funciona melhor quando o aplicativo gera conteúdo estático no servidor antes de enviá-lo ao navegador. Adicione o [client_secret](https://docs.stripe.com/api/setup_intents/object.md#setup_intent_object-client_secret) ao formulário de checkout. No código do lado do servidor, recupere o segredo do cliente do SetupIntent: #### Ruby ```erb
``` ```ruby get '/checkout' do @intent = # ... Fetch or create the SetupIntent erb :checkout end ``` > #### Uso do Radar > > Ao salvar a forma de pagamento de um cliente sem um pagamento inicial, o [Radar](https://docs.stripe.com/radar.md) não age no SetupIntent por padrão. Se quiser ativá-lo como padrão, acesse as [configurações do Radar](https://dashboard.stripe.com/settings/radar) e habilite **Use o Radar em formas de pagamento salvas para uso futuro**. ## Coletar dados de pagamento [Lado do cliente] Você está com tudo pronto para coletar dados de pagamento no cliente com o [Payment Element](https://docs.stripe.com/payments/payment-element.md). O Payment Element é um componente de IU integrado 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 à Stripe com segurança por uma conexão HTTPS. O endereço da página de checkout precisa começar com `https://` em vez de `http://` para que sua integração funcione. Você pode testar sua integração sem fazer isso, mas lembre-se de [habilitar o HTTPS](https://docs.stripe.com/security/guide.md#tls) quando estiver tudo pronto para você aceitar pagamentos em tempo real. #### HTML + JS ### Configurar Stripe.js O Payment Element está disponível automaticamente como um recurso do Stripe.js. Inclua o script do 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 você mesmo uma cópia dele. ```html Checkout ``` Crie uma instância da Stripe com o seguinte JavaScript na sua página de checkout: ```javascript // 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('<>'); ``` ### Adicione o Payment Element à sua página de configuração de pagamentos O Payment Element precisa de um lugar para residir na sua página de configuração de pagamentos. Crie um nó DOM vazio (contêiner) com um ID único no seu formulário de pagamento: ```html
``` Quando o formulário anterior for carregado, crie uma instância do Element Pagamento e monte-o no nó DOM do contêiner. Passe o [segredo do cliente](https://docs.stripe.com/api/setup_intents/object.md#setup_intent_object-client_secret) da etapa anterior nas `options` ao criar a instância do [Elements](https://docs.stripe.com/js/elements_object/create): ```javascript const options = { clientSecret: '{{CLIENT_SECRET}}', // Fully customizable with appearance API. appearance: {/*...*/}, }; // Set up Stripe.js and Elements using the SetupIntent's client secretconst 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 ao passar o [objeto de aparência](https://docs.stripe.com/js/elements_object/create#stripe_elements-options-appearance) nas `opções` ao criar a instância `elements`. O Stripe Elements é uma cobrança de componentes de IU. Para personalizar ainda mais o formulário ou recolher informações de clientes diferentes, consulte a [documentação Elements](https://docs.stripe.com/payments/elements.md). ### Solicitar token de comerciante do Apple Pay Se você aceitar pagamentos pela Apple Pay, recomendamos configurar a `opção` [applePay](https://docs.stripe.com/js/elements_object/create_payment_element#payment_element_create-options-applePay) para modificar o que é exibido na interface da Apple Pay. Ao fazer isso, os [tokens de comerciante](https://docs.stripe.com/apple-pay/merchant-tokens.md?pay-element=web-pe) da Apple Pay são usados. O exemplo a seguir mostra uma configuração para um pagamento que começa em 5 de janeiro de 2030. Essas informações serão refletidas na interface da Apple Pay. ```javascript const paymentElement = elements.create('payment', { applePay: { deferredPaymentRequest: { paymentDescription: 'My deferred payment', managementURL: 'https://example.com/billing', deferredBilling: { amount: 2500, label: 'Deferred Fee', deferredPaymentDate: new Date('2030-01-05') }, } }, // Other options }); ``` #### React ### Configurar Stripe.js Instale o [React Stripe.js](https://www.npmjs.com/package/@stripe/react-stripe-js) e o [carregador do Stripe.js](https://www.npmjs.com/package/@stripe/stripe-js) do registro público npm. ```bash npm install --save @stripe/react-stripe-js @stripe/stripe-js ``` ### Adicione e configure o provedor do Elements à sua página de configuração de pagamentos Para usar o componente Payment Element, insira o componente da página de configuração de pagamento em um [provedor do Elements](https://docs.stripe.com/sdks/stripejs-react.md#elements-provider). Chame `loadStripe` com sua chave publicável e passe a `Promise` devolvida ao provedor do `Elements`. Além disso, passe o [segredo do cliente](https://docs.stripe.com/api/setup_intents/object.md#setup_intent_object-client_secret) da etapa anterior como `options` para o provedor do `Elements`. ```jsx import React from 'react'; import ReactDOM from 'react-dom'; import {Elements} from '@stripe/react-stripe-js'; import {loadStripe} from '@stripe/stripe-js'; import SetupForm from './SetupForm'; // 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() { const options = { // passing the SetupIntent's client secret clientSecret: '{{CLIENT_SECRET}}', // Fully customizable with appearance API. appearance: {/*...*/}, }; return ( ); }; ReactDOM.render(, document.getElementById('root')); ``` ### Adicione o componente Payment Element Use o componente `PaymentElement` para criar seu formulário: ```jsx import React from 'react'; import {PaymentElement} from '@stripe/react-stripe-js'; const SetupForm = () => { return (
); }; export default SetupForm; ``` O Stripe Elements é uma coleção de componentes de IU prontos para uso. Para personalizar ainda mais o formulário ou coletar outros dados do cliente, consulte a [documentação do Elements](https://docs.stripe.com/payments/elements.md). 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](https://docs.stripe.com/js/elements_object/create#stripe_elements-options-appearance) para `options` ao criar o provedor do `Elements`. ### Solicitar token de comerciante do Apple Pay Se você aceitar pagamentos pela Apple Pay, recomendamos configurar a `opção` [applePay](https://docs.stripe.com/js/elements_object/create_payment_element#payment_element_create-options-applePay) para modificar o que é exibido na interface da Apple Pay. Ao fazer isso, os [tokens de comerciante](https://docs.stripe.com/apple-pay/merchant-tokens.md?pay-element=web-pe) da Apple Pay são usados. O exemplo a seguir mostra uma configuração para um pagamento que começa em 5 de janeiro de 2030. Essas informações serão refletidas na interface da Apple Pay. ```jsx import React from 'react'; import {PaymentElement} from '@stripe/react-stripe-js'; const SetupForm = () => { const options = { applePay: { deferredPaymentRequest: { paymentDescription: 'My deferred payment', managementURL: 'https://example.com/billing', deferredBilling: { amount: 2500, label: 'Deferred Fee', deferredPaymentDate: new Date('2030-01-05') }, } }, // Other options }; return (
); }; export default SetupForm; ``` ### Configurar moeda Ao usar SetupIntents com [automatic_payment_methods](https://docs.stripe.com/api/setup_intents/create.md#create_setup_intent-automatic_payment_methods) , você pode especificar a moeda ao [criar o Payment Element](https://docs.stripe.com/js/elements_object/create#stripe_elements-options-currency). O Payment Element processa as formas de pagamento habilitadas que aceitam a moeda informada. Para obter mais detalhes, consulte [a documentação do Payment Element](https://docs.stripe.com/payments/payment-methods/integration-options.md). ### Solicitar endereços Por padrão, o Payment Element só recolhe os detalhes necessários do endereço de faturamento. Alguns comportamentos, como [calcular impostos](https://docs.stripe.com/api/tax/calculations/create.md) ou inserir detalhes de entrega, exigem o endereço completo do cliente. Você pode: - Use o [Address Element](https://docs.stripe.com/elements/address-element.md) para aproveitar os recursos de autocompletar e traduzir para recolher o endereço completo do cliente. Isso ajuda a garantir um cálculo tributário mais preciso. - Obtenha os detalhes do endereço usando seu próprio formulário personalizado. ## Optional: Link in your checkout page [Lado do cliente] Permita que seu cliente faça checkout mais rápido usando [Link](https://docs.stripe.com/payments/link.md) no [Payment Element](https://docs.stripe.com/payments/payment-element.md). Você pode preencher automaticamente os dados de qualquer cliente conectado que já usa Link, independentemente de ter salvado os dados inicialmente em Link com outra empresa. A integração padrão do Payment Element inclui uma solicitação Link no cartão. Para gerenciar Link no Payment Element, acesse as configurações da sua [forma de pagamento](https://dashboard.stripe.com/settings/payment_methods). ![Authenticate or enroll with Link directly in the Payment Element during checkout](https://b.stripecdn.com/docs-statics-srv/assets/link-in-pe.2efb5138a4708b781b8a913ebddd9aba.png) Recolher um endereço de e-mail do cliente para autenticação ou inscrição no Link ### Opções de integração Há duas formas de integrar o Link com o Payment Element. A Stripe recomenda passar um endereço de e-mail do cliente para o Payment Element, se disponível. Lembre-se de considerar o fluxo de checkout da sua compra ao escolher entre essas opções: | Opção de integração | Fluxo de checkout | Descrição | | ------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Transfira um endereço de e-mail do cliente para o Payment Element (Recommended) | - Seu cliente insere o endereço de e-mail antes de chegar à página de checkout (em uma etapa anterior de criação de conta, por exemplo). - Você prefere usar seu próprio campo de entrada de e-mail. | Passe automaticamente um endereço de e-mail do cliente para o Payment Element. Nesse cenário, um cliente autentica-se no Link diretamente no formulário de pagamento, em vez de um componente de IU separado. | | Recolher um endereço de e-mail do cliente no Payment Element | - Seus clientes podem optar por inserir o e-mail e se autenticar ou se cadastrar com o Link diretamente no Payment Element durante o checkout. - Não é necessária nenhuma alteração no código. | Se um cliente ainda não tiver se cadastrado no Link e escolher uma forma de pagamento compatível no Payment Element, ele será solicitado a salvar seus dados usando o Link. Para aqueles que já estão cadastrados, o Link preenche automaticamente suas informações de pagamento. | Use [defaultValues](https://docs.stripe.com/js/elements_object/create_payment_element#payment_element_create-options-defaultValues) para transferir um endereço de e-mail de cliente para o Payment Element. ```javascript const paymentElement = elements.create('payment', { defaultValues: { billingDetails: { email: 'foo@bar.com', } }, // Other options }); ``` Para obter mais informações, leia como [criar uma página de checkout personalizada que inclua o Link](https://docs.stripe.com/payments/link/add-link-elements-integration.md). ## Optional: Salvar e recuperar formas de pagamento do cliente Você pode configurar o Payment Element para salvar as formas de pagamento do seu cliente para uso futuro. Esta seção mostra como integrar o [recurso de formas de pagamento salvas](https://docs.stripe.com/payments/save-customer-payment-methods.md), que permite que o Payment Element: - Solicitar consentimento dos compradores para salvar uma forma de pagamento - Salvar formas de pagamento quando os compradores derem consentimento - Exibir formas de pagamento salvas aos compradores para compras futuras - [Atualize automaticamente cartões perdidos ou vencidos](https://docs.stripe.com/payments/cards/overview.md#automatic-card-updates) quando são substituídos pelos compradores ![O Payment Element e uma caixa de seleção forma de pagamento salva](https://b.stripecdn.com/docs-statics-srv/assets/spm-save.fe0b24afd0f0a06e0cf4eecb0ce2403a.png) Salve formas de pagamento. ![O Payment Element com uma forma de pagamento salva selecionada](https://b.stripecdn.com/docs-statics-srv/assets/spm-saved.5dba5a8a190a9a0e9f1a99271bed3f4b.png) Reutilize uma forma de pagamento salva anteriormente. ### Habilite o salvamento da forma de pagamento no Payment Element Crie uma [CustomerSession](https://docs.stripe.com/api/customer_sessions/.md) no seu servidor fornecendo o ID do cliente (usando `customer` para um objeto `Customer` ou `customer_account` para um objeto `Account` configurado para o cliente) e habilitando o componente [payment_element](https://docs.stripe.com/api/customer_sessions/object.md#customer_session_object-components-payment_element) para a sessão. Configure quais [features](https://docs.stripe.com/api/customer_sessions/create.md#create_customer_session-components-payment_element-features) de formas de pagamento salvos você deseja ativar. Por exemplo, ao habilitar [payment_method_save](https://docs.stripe.com/api/customer_sessions/create.md#create_customer_session-components-payment_element-features-payment_method_save), é exibida uma caixa de seleção que permite aos clientes salvar seus dados de pagamento para uso futuro. Você pode especificar `setup_future_usage` em um PaymentIntent ou em uma Checkout Session para substituir o comportamento padrão de salvamento de formas de pagamento. Isso garante que você salve automaticamente a forma de pagamento para uso futuro, mesmo que o cliente não escolha explicitamente salvá-la. Se você pretende definir `setup_future_usage`, não configure `payment_method_save_usage` na mesma transação de pagamento, pois isso causará um erro de integração. > #### Use a API Accounts v2 para representar clientes > > A API Accounts v2 está geralmente disponível para usuários do Connect e em prévia pública para outros usuários da Stripe. Se faz parte da prévia de Accounts v2, é necessário [especificar uma versão de prévia](https://docs.stripe.com/api-v2-overview.md#sdk-and-api-versioning) no seu código. > > Para solicitar acesso à prévia de Accounts v2, > > For most use cases, we recommend [modeling your customers as customer-configured Account objects](https://docs.stripe.com/accounts-v2/use-accounts-as-customers.md) instead of using [Customer](https://docs.stripe.com/api/customers.md) objects. #### Accounts v2 #### Ruby ```ruby # Don't put any keys in code. See https://docs.stripe.com/keys-best-practices. # Find your keys at https://dashboard.stripe.com/apikeys. client = Stripe::StripeClient.new('<>') post '/create-intent-and-customer-session' do intent = client.v1.setup_intents.create({ automatic_payment_methods: {enabled: true}, customer_account: {{CUSTOMER_ACCOUNT_ID}}, }) customer_session = client.v1.customer_sessions.create({ customer_account: {{CUSTOMER_ACCOUNT_ID}}, components: { payment_element: { enabled: true, features: { payment_method_redisplay: 'enabled', payment_method_save: 'enabled', payment_method_save_usage: 'off_session', payment_method_remove: 'enabled', }, }, }, }) { client_secret: intent.client_secret, customer_session_client_secret: customer_session.client_secret }.to_json end ``` #### Clientes v1 #### Ruby ```ruby # Don't put any keys in code. See https://docs.stripe.com/keys-best-practices. # Find your keys at https://dashboard.stripe.com/apikeys. client = Stripe::StripeClient.new('<>') post '/create-intent-and-customer-session' do intent = client.v1.setup_intents.create({ # In the latest version of the API, specifying the `automatic_payment_methods` parameter # is optional because Stripe enables its functionality by default. automatic_payment_methods: {enabled: true}, customer: {{CUSTOMER_ID}}, }) customer_session = client.v1.customer_sessions.create({ customer: {{CUSTOMER_ID}}, components: { payment_element: { enabled: true, features: { payment_method_redisplay: 'enabled', payment_method_save: 'enabled', payment_method_save_usage: 'off_session', payment_method_remove: 'enabled', }, }, }, }) { client_secret: intent.client_secret, customer_session_client_secret: customer_session.client_secret }.to_json end ``` Sua instância do Elements usa o *segredo do cliente* (A client secret is used with your publishable key to authenticate a request for a single object. Each client secret is unique to the object it's associated with) da CustomerSession para acessar as formas de pagamento salvas desse cliente. [Gerencie erros](https://docs.stripe.com/error-handling.md) corretamente ao criar a CustomerSession. Se ocorrer um erro, você não precisará fornecer o segredo do cliente da CustomerSession para a instância do Elements, pois é opcional. Crie a instância do Elements usando os segredos do cliente para SetupIntent e CustomerSession. Em seguida, use essa instância do Elements para criar um Payment Element. ```javascript // Create the CustomerSession and obtain its clientSecret const res = await fetch("/create-intent-and-customer-session", { method: "POST" }); const { customer_session_client_secret: customerSessionClientSecret } = await res.json(); const elementsOptions = { clientSecret: '{{CLIENT_SECRET}}',customerSessionClientSecret, // Fully customizable with appearance API. appearance: {/*...*/}, }; // Set up Stripe.js and Elements to use in checkout form, passing the client secret // and CustomerSession's client secret obtained in a previous step const elements = stripe.elements(elementsOptions); // Create and mount the Payment Element const paymentElementOptions = { layout: 'accordion'}; const paymentElement = elements.create('payment', paymentElementOptions); paymentElement.mount('#payment-element'); ``` Quando você confirma o SetupIntent, o Stripe.js controla automaticamente a [allow_redisplay](https://docs.stripe.com/api/payment_methods/object.md#payment_method_object-allow_redisplay) definida no PaymentMethod, dependendo de o cliente ter marcado a caixa para salvar os dados de pagamento. ### Detectar a seleção de uma forma de pagamento salva Para controlar o conteúdo dinâmico quando uma forma de pagamento salva é selecionada, ouça o evento `change` do Payment Element, que é preenchido com a forma de pagamento selecionada. ```javascript paymentElement.on('change', function(event) { if (event.value.payment_method) { // Control dynamic content if a saved payment method is selected } }) ``` ## Envie os dados do pagamento para a Stripe [Lado do cliente] Use [stripe.confirmSetup](https://docs.stripe.com/js/setup_intents/confirm_setup) para concluir a configuração usando os detalhes coletados pelo Element Pagamento. Forneça um [return_url](https://docs.stripe.com/api/setup_intents/create.md#create_setup_intent-return_url) a esta função para que a Stripe possa redirecionar o usuário após a conclusão da configuração. Primeiro, poderemos redirecioná-lo a um site intermediário, como uma página de autorização do banco, antes de redirecioná-lo ao `return_url`. Se o seu cliente salvar os dados do cartão, nós o redirecionaremos imediatamente para o `return_url` quando a configuração estiver concluída. Se você não quiser redirecionar para pagamentos com cartão, defina [redirecionar](https://docs.stripe.com/js/setup_intents/confirm_setup#confirm_setup_intent-options-redirect) como `if_required`. Isso somente redireciona os clientes que fazem checkout com formas de pagamento baseadas em redirecionamento. #### HTML + JS ```javascript const form = document.getElementById('payment-form'); form.addEventListener('submit', async (event) => { event.preventDefault(); const {error} = await stripe.confirmSetup({ //`Elements` instance that was used to create the Payment Element elements, confirmParams: { return_url: 'https://example.com/account/payments/setup-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`. } }); ``` #### React Para chamar [stripe.confirmSetup](https://docs.stripe.com/js/setup_intents/confirm_setup) do seu componente de formulário de pagamento, use os hooks [useStripe](https://docs.stripe.com/sdks/stripejs-react.md#usestripe-hook) e [useElements](https://docs.stripe.com/sdks/stripejs-react.md#useelements-hook). Se preferir componentes de classe tradicionais em vez de hooks, use um [ElementsConsumer](https://docs.stripe.com/sdks/stripejs-react.md#elements-consumer). ```jsx import React, {useState} from 'react'; import {useStripe, useElements, PaymentElement} from '@stripe/react-stripe-js'; const SetupForm = () => { const stripe = useStripe(); const elements = useElements(); const [errorMessage, setErrorMessage] = useState(null); const handleSubmit = async (event) => { // We don't want to let default form submission happen here, // which would refresh the page. event.preventDefault(); if (!stripe || !elements) { // Stripe.js hasn't yet loaded. // Make sure to disable form submission until Stripe.js has loaded. return null; } const {error} = await stripe.confirmSetup({ //`Elements` instance that was used to create the Payment Element elements, confirmParams: { return_url: 'https://example.com/account/payments/setup-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) setErrorMessage(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`. } }; return (
{/* Show error message to your customers */} {errorMessage &&
{errorMessage}
} ) }; export default SetupForm; ``` Certifique-se de que o `return_url` corresponda a uma página em seu site que [forneça o status](https://docs.stripe.com/payments/payment-intents/verifying-status.md) do `SetupIntent`. A Stripe fornece os seguintes parâmetros de consulta de URL para verificar o status quando redirecionamos o cliente para o `return_url`. Você também pode anexar seus próprios parâmetros de consulta ao fornecer o `return_url`, e eles persistem durante o processo de redirecionamento. | Parâmetro | Descrição | | ---------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- | | `setup_intent` | O identificador único do `SetupIntent`. | | `setup_intent_client_secret` | O [segredo do cliente](https://docs.stripe.com/api/setup_intents/object.md#setup_intent_object-client_secret) do objeto `SetupIntent`. | Você pode usar [stripe.retrieveSetupIntent](https://docs.stripe.com/js/setup_intents/retrieve_setup_intent) para recuperar o `SetupIntent` usando o parâmetro de consulta `setup_intent_client_secret`. A confirmação bem-sucedida do `SetupIntent` salva o ID do `PaymentMethod` resultante (em `result.setupIntent.payment_method`) na `Account` ou no `Customer` configurado pelo cliente informado. #### HTML + JS ```javascript // Initialize Stripe.js using your publishable key const stripe = Stripe('{PUBLISHABLE_KEY}'); // Retrieve the "setup_intent_client_secret" query parameter appended to // your return_url by Stripe.js const clientSecret = new URLSearchParams(window.location.search).get( 'setup_intent_client_secret' ); // Retrieve the SetupIntent stripe.retrieveSetupIntent(clientSecret).then(({setupIntent}) => { const message = document.querySelector('#message') // Inspect the SetupIntent `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 (setupIntent.status) { case 'succeeded': { message.innerText = 'Success! Your payment method has been saved.'; break; } case 'processing': { message.innerText = "Processing payment details. We'll update you when processing is complete."; break; } case 'requires_payment_method': { message.innerText = 'Failed to process payment details. Please try another payment method.'; // Redirect your user back to your payment page to attempt collecting // payment again break; } } }); ``` #### React ```jsx // PaymentStatus.jsx import React, {useState, useEffect} from 'react'; import {useStripe} from '@stripe/react-stripe-js'; const PaymentStatus = () => { const stripe = useStripe(); const [message, setMessage] = useState(null); useEffect(() => { if (!stripe) { return; } // Retrieve the "setup_intent_client_secret" query parameter appended to // your return_url by Stripe.js const clientSecret = new URLSearchParams(window.location.search).get( 'setup_intent_client_secret' ); // Retrieve the SetupIntent stripe .retrieveSetupIntent(clientSecret) .then(({setupIntent}) => { // Inspect the SetupIntent `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 (setupIntent.status) { case 'succeeded': setMessage('Success! Your payment method has been saved.'); break; case 'processing': setMessage("Processing payment details. We'll update you when processing is complete."); break; case 'requires_payment_method': // Redirect your user back to your payment page to attempt collecting // payment again setMessage('Failed to process payment details. Please try another payment method.'); break; } }); }, [stripe]); return message }; export default PaymentStatus; ``` > 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 sessões, o que impede que você rastreie a sessão completa. ## Cobrar mais tarde a forma de pagamento salva [Lado do servidor] > #### Conformidade > > Você é responsável por cumprir todas as leis, regulamentos e regras de rede aplicáveis ao salvar os dados de pagamento de um cliente. Quando exibir formas de pagamento passadas ao seu cliente final para compras futuras, liste as formas de pagamento para as quais obteve consentimento do cliente para salvar os dados para esse uso futuro específico. Para diferenciar entre formas de pagamento vinculadas a clientes que podem e não podem ser apresentados ao seu cliente final como uma forma de pagamento salva para compras futuras, use o parâmetro [allow_redisplay](https://docs.stripe.com/api/payment_methods/object.md#payment_method_object-allow_redisplay). Para encontrar uma forma de pagamento a ser cobrada, liste as formas de pagamento associadas ao seu cliente. Este exemplo lista cartões, mas você pode listar qualquer [tipo](https://docs.stripe.com/api/payment_methods/object.md#payment_method_object-type) aceito. > #### Use a API Accounts v2 para representar clientes > > A API Accounts v2 está geralmente disponível para usuários do Connect e em prévia pública para outros usuários da Stripe. Se faz parte da prévia de Accounts v2, é necessário [especificar uma versão de prévia](https://docs.stripe.com/api-v2-overview.md#sdk-and-api-versioning) no seu código. > > Para solicitar acesso à prévia de Accounts v2, > > For most use cases, we recommend [modeling your customers as customer-configured Account objects](https://docs.stripe.com/accounts-v2/use-accounts-as-customers.md) instead of using [Customer](https://docs.stripe.com/api/customers.md) objects. #### Accounts v2 ```curl curl -G https://api.stripe.com/v1/payment_methods \ -u "<>:" \ -d "customer_account={{CUSTOMERACCOUNT_ID}}" \ -d type=card ``` #### Clientes v1 ```curl curl -G https://api.stripe.com/v1/payment_methods \ -u "<>:" \ -d "customer={{CUSTOMER_ID}}" \ -d type=card ``` Quando estiver pronto para cobrar seu cliente *off-session* (A payment is described as off-session if it occurs without the direct involvement of the customer, using previously-collected payment information), use o ID do `Cliente` ou da `Conta` configurada pelo cliente e o ID `PaymentMethod` para criar um `PaymentIntent` com o valor e a moeda do pagamento. Defina alguns outros parâmetros para efetuar o pagamento fora da sessão: - Defina [off_session](https://docs.stripe.com/api/payment_intents/create.md#create_payment_intent-off_session) como verdadeiro para indicar que o cliente não está no seu fluxo de checkout, a fim de responder a quaisquer solicitações de autenticação. Se, durante o fluxo de checkout, um parceiro (como um emissor de cartão ou banco) solicitar autenticação, a Stripe solicitará isenções usando as informações do cliente de uma transação *on-session* (A payment is described as on-session if it occurs while the customer is actively in your checkout flow and able to authenticate the payment method) anterior. Se as condições para isenção não forem atendidas, o `PaymentIntent` poderá gerar um erro. - Defina [confirm](https://docs.stripe.com/api/payment_intents/create.md#create_payment_intent-confirm) como verdadeiro para acionar a confirmação imediatamente após a criação do `PaymentIntent`. - Defina [payment_method](https://docs.stripe.com/api.md#create_payment_intent-payment_method) como o ID do `PaymentMethod`. - Dependendo de como você representa os clientes em sua integração, defina [customer_account](https://docs.stripe.com/api/payment_intents/create.md#create_payment_intent-customer_account) como o ID da `conta` configurada pelo cliente ou [cliente](https://docs.stripe.com/api.md#create_payment_intent-customer) como o ID do `cliente`. #### Contas v2 ```curl curl https://api.stripe.com/v1/payment_intents \ -u "<>:" \ -d amount=1099 \ -d currency=usd \ -d "automatic_payment_methods[enabled]=true" \ -d "customer_account={{CUSTOMERACCOUNT_ID}}" \ -d payment_method={{PAYMENT_METHOD_ID}} \ --data-urlencode "return_url=https://example.com/order/123/complete" \ -d off_session=true \ -d confirm=true ``` #### Clientes v1 ```curl curl https://api.stripe.com/v1/payment_intents \ -u "<>:" \ -d amount=1099 \ -d currency=usd \ -d "automatic_payment_methods[enabled]=true" \ -d "customer={{CUSTOMER_ID}}" \ -d payment_method={{PAYMENT_METHOD_ID}} \ --data-urlencode "return_url=https://example.com/order/123/complete" \ -d off_session=true \ -d confirm=true ``` Quando uma tentativa de pagamento falha, a solicitação também falha (código de status HTTP 402) e o status do PaymentIntent fica sendo *requires\_payment\_method* (This status appears as "requires_source" in API versions before 2019-02-11). Você deverá notificar o cliente para que ele acesse novamente seu aplicativo para finalizar o pagamento (envie um e-mail ou notificação pelo aplicativo, por exemplo). Verifique o código do [erro](https://docs.stripe.com/api/errors/handling.md) indicado pela biblioteca da API Stripe. Se o pagamento falhou com o código [authentication_required](https://docs.stripe.com/declines/codes.md), use o segredo do cliente do PaymentIntent recusado com confirmPayment para permitir que o cliente autentique o pagamento. ```javascript const form = document.getElementById('payment-form'); form.addEventListener('submit', async (event) => { event.preventDefault(); const {error} = await stripe.confirmPayment({ // The client secret of the PaymentIntent clientSecret, 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`. } }); ``` > `stripe.confirmPayment` pode levar vários segundos para finalizar. Durante esse período, desative o formulário para impedir que seja reenviado e apresente 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 executar etapas adicionais para finalizar o pagamento, como autenticação, o Stripe.js o orientará durante a execução. Se o pagamento falhar por outros motivos, como insuficiência de fundos, envie o cliente para uma página de pagamento para que ele insira outra forma de pagamento. Você pode reaproveitar o PaymentIntent atual para tentar repetir o pagamento com os dados do novo pagamento. ## Testar a integração Use os detalhes de pagamento de teste e a página de redirecionamento de teste para verificar sua integração. Clique nas guias abaixo para ver os detalhes de cada forma de pagamento. #### Cartões | Forma de pagamento | Cenário | Como testar | | ------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- | | Cartão de crédito | A configuração do cartão é realizada e não precisa de *autenticação* (Strong Customer Authentication (SCA) is a regulatory requirement in effect as of September 14, 2019, that impacts many European online payments. It requires customers to use two-factor authentication like 3D Secure to verify their purchase). | Preencha o formulário do cartão de crédito usando o número de cartão de crédito `4242 4242 4242 4242` com qualquer validade, CVC e código postal. | | Cartão de crédito | O cartão precisa de autenticação para a configuração inicial e depois pode ser utilizado em pagamentos subsequentes. | Preencha o formulário do cartão de crédito usando o número do cartão de crédito `4000 0025 0000 3155` com qualquer validade, CVC e código postal. | | Cartão de crédito | O cartão precisa de autenticação para a configuração inicial e também precisa de autenticação para pagamentos subsequentes. | Preencha o formulário do cartão de crédito usando o número do cartão de crédito `4000 0027 6000 3184` com qualquer validade, CVC e código postal. | | Cartão de crédito | O cartão é recusado durante a configuração. | Preencha o formulário do cartão de crédito usando o número do cartão de crédito `4000 0000 0000 9995` com qualquer validade, CVC e código postal. | #### Débito bancário autenticado | Forma de pagamento | Cenário | Como testar | | ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Bancontact | Seu cliente configura corretamente uma forma de pagamento de débito automático SEPA para uso futuro usando Bancontact. | Use qualquer nome no formulário do Bancontact e clique em **Autorizar configuração de teste** na página de redirecionamento. | | Bancontact | Seu cliente não faz a autenticação na página de redirecionamento do Bancontact. | Use qualquer nome no formulário do Bancontact e clique em **Falhar a configuração de teste** na página de redirecionamento. | | Débito automático BECS | O cliente paga com débito automático BECS. | Preencha o formulário usando o número de conta `900123456`. Inicialmente, o status confirmado do `PaymentIntent` passa para `em processamento` e, três minutos depois, para `concluído`. | | Débito automático BECS | O pagamento do cliente falha com um código de erro `account_closed`. | Preencha o formulário usando o número de conta `111111113`. | | iDEAL | Seu cliente configura corretamente uma forma de pagamento de [débito automático SEPA](https://docs.stripe.com/payments/sepa-debit.md) para uso futuro usando iDEAL. | Use qualquer nome e banco no formulário do iDEAL e clique em **Autorizar configuração de teste** na página de redirecionamento. | | iDEAL | Seu cliente não faz a autenticação na página de redirecionamento do iDEAL. | Selecione qualquer banco e use qualquer nome no formulário do iDEAL e clique em **Falhar a configuração de teste** na página de redirecionamento. | #### Débitos bancários | Forma de pagamento | Cenário | Como testar | | ---------------------- | -------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Débito automático SEPA | O cliente paga com débito automático SEPA. | Preencha o formulário usando o número de conta `AT321904300235473204`. Inicialmente, o status confirmado do `PaymentIntent` passa para `em processamento` e, três minutos depois, para `concluído`. | | Débito automático SEPA | O status do `PaymentIntent` do cliente passa de `en processamento` para `requires_payment_method`. | Preencha o formulário usando o número de conta `AT861904300235473202`. | ### Teste a cobrança de um PaymentMethod de débito SEPA A confirmação do `SetupIntent` utilizando iDEAL, Bancontact ou Sofort gera um [débito automático SEPA](https://docs.stripe.com/payments/sepa-debit.md) *PaymentMethod* (PaymentMethods represent your customer's payment instruments, used with the Payment Intents or Setup Intents APIs). O débito automático SEPA é uma forma de pagamento com [notificação posterior](https://docs.stripe.com/payments/payment-methods.md#payment-notification) que passa por um estado de `processamento` intermediário antes de, alguns dias depois, passar para um estado de `concluído` ou `requires_payment_method` #### E-mail Defina `payment_method.billing_details.email` para um dos seguintes valores para testar as transições de status do `PaymentIntent`. Você pode incluir seu próprio texto personalizado no início do endereço de e-mail, seguido por um underline. Por exemplo, `test_1_generatedSepaDebitIntentsFail@example.com` resulta em um PaymentMethod de débito automático SEPA que sempre falha quando usado com um `PaymentIntent`. | Endereço de e-mail | Descrição | | ------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------- | | `generatedSepaDebitIntentsSucceed@example.com` | O status do `PaymentIntent` muda de `processing` para `succeeded`. | | `generatedSepaDebitIntentsSucceedDelayed@example.com` | O status do `PaymentIntent` passa de `processing` para `succeeded` após pelo menos três minutos. | | `generatedSepaDebitIntentsFail@example.com` | O status do `PaymentIntent` muda de `processing` para `requires_payment_method`. | | `generatedSepaDebitIntentsFailDelayed@example.com` | O status do `PaymentIntent` passa de `processing` para `requires_payment_method` após pelo menos três minutos. | | `generatedSepaDebitIntentsSucceedDisputed@example.com` | O status do `PaymentIntent` passa de `processing` para `succeeded`, mas uma contestação é imediatamente criada. | | `generatedSepaDebitIntentsFailsDueToInsufficientFunds@example.com` | O status do `PaymentIntent` passa de `processing` para `requires_payment_method` com o código de falha `insufficient_funds`. | #### PaymentMethod Use estes PaymentMethods para testar as transições de status do `PaymentIntent`. Esses tokens são úteis para testes automatizados, permitindo anexar imediatamente o PaymentMethod ao SetupIntent no servidor. | Forma de pagamento | Descrição | | -------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------- | | `pm_bancontact_generatedSepaDebitIntentsSucceed` | O status do `PaymentIntent` muda de `processing` para `succeeded`. | | `pm_bancontact_generatedSepaDebitIntentsSucceedDelayed` | O status do `PaymentIntent` passa de `processing` para `succeeded` após pelo menos três minutos. | | `pm_bancontact_generatedSepaDebitIntentsFail` | O status do `PaymentIntent` muda de `processing` para `requires_payment_method`. | | `pm_bancontact_generatedSepaDebitIntentsFailDelayed` | O status do `PaymentIntent` passa de `processing` para `requires_payment_method` após pelo menos três minutos. | | `pm_bancontact_generatedSepaDebitIntentsSucceedDisputed` | O status do `PaymentIntent` passa de `processing` para `succeeded`, mas uma contestação é imediatamente criada. | | `pm_bancontact_generatedSepaDebitIntentsFailsDueToInsufficientFunds` | O status do `PaymentIntent` passa de `processing` para `requires_payment_method` com o código de falha `insufficient_funds`. | ## Optional: Personalizar o layout [Lado do cliente] Você pode personalizar o layout do Payment Element (sanfona ou guias) para que se ajuste à sua interface de checkout. Para obter mais informações sobre cada uma das propriedades, consulte [elements.create](https://docs.stripe.com/js/elements_object/create_payment_element#payment_element_create-options). #### Sanfona Você pode começar a usar os recursos de layout passando um `type` de layout e outras propriedades opcionais ao criar o Payment Element: ```javascript const paymentElement = elements.create('payment', { layout: { type: 'accordion', defaultCollapsed: false, radios: 'always', spacedAccordionItems: false } }); ``` #### Guias ### Especifique o layout Defina o valor do layout como `tabs`. Você também tem a opção de especificar outras propriedades, como no exemplo a seguir: ```javascript const paymentElement = elements.create('payment', { layout: { type: 'tabs', defaultCollapsed: false, } }); ``` A imagem a seguir é o mesmo Payment Element renderizado usando diferentes configurações de layout: ![Três experiências de formulário de checkout](https://b.stripecdn.com/docs-statics-srv/assets/pe_layout_example.525f78bcb99b95e49be92e5dd34df439.png) Layouts do Payment Element ## Optional: Apple Pay e Google Pay [Lado do cliente] Quando você [habilita pagamentos com cartão](https://docs.stripe.com/payments/save-and-reuse.md?platform=web&ui=elements#create-intent), exibimos o Apple Pay e o Google Pay para clientes cujo ambiente atende às [condições de exibição da carteira](https://docs.stripe.com/testing/wallets.md). Para aceitar pagamentos com essas carteiras, você também deve: - Habilitá-las nas [configurações de formas de pagamento](https://dashboard.stripe.com/settings/payment_methods). O Apple Pay é habilitado por padrão. - [Registre seu domínio](https://docs.stripe.com/payments/payment-methods/pmd-registration.md). > #### Testes regionais > > O Stripe Elements não aceita o Google Pay ou Apple Pay para contas e clientes da Stripe na Índia. Portanto, não é possível testar sua integração do Google Pay ou Apple Pay se o endereço IP do testador estiver na Índia, mesmo que a conta Stripe esteja localizada fora da Índia. ## 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](https://stripe.com/legal/privacy-center#as-a-business-user-what-notice-do-i-provide-to-my-end-customers-about-stripe). ## See also - [Aceitar um pagamento](https://docs.stripe.com/payments/accept-a-payment.md) - [Salvar dados de pagamento durante o pagamento](https://docs.stripe.com/payments/save-during-payment.md) - [A API Elements Appearance](https://docs.stripe.com/elements/appearance-api.md) - [Enviar os fatores de risco completos](https://docs.stripe.com/radar/optimize-risk-factors.md)