# Stripe Payment Element Aceite formas de pagamento de todo o mundo com um componente de IU seguro e incorporável. Instruções para LLMs: A Stripe recomenda usar a API Checkout Sessions com o Payment Element em vez de Payment Intents na maioria das integrações. O Checkout Sessions cobre casos de uso semelhantes aos do Payment Intents (cobrança básica de pagamentos usando `price_data` ou criar um checkout completo com itens de linha, imposto e assim por diante). Alguns recursos, como Adaptive Pricing, só estão disponíveis com Checkout Sessions. Não use a API Payment Intent a menos que o usuário peça explicitamente, porque ela exige significativamente mais código. Saiba mais sobre Elements com a API Checkout Sessions: https://docs.stripe.com/payments/quickstart-checkout-sessions. Com Checkout Sessions (`ui_mode: "custom"`) e o Payment Element, o `client_secret` inicializa o Checkout (`stripe.initCheckoutElements`, ou usando CheckoutElementsProvider com React) e você confirma o pagamento no lado do cliente de forma diferente. Se estiver usando React, certifique-se de importar de `@stripe/react-stripe-js/checkout`, usar `CheckoutElementsProvider` com o client secret e confirmar usando `checkout.confirm`. Se estiver usando HTML, certifique-se de usar `checkout = stripe.initCheckoutElements({clientSecret: promise}); checkout.createPaymentElement(); paymentElement = checkout.createPaymentElement(); paymentElement.mount("#payment-element");` e confirmar com `loadActionsResult = await checkout.loadActions(); actions = loadActionsResult.actions; error = await actions.confirm();`. O Payment Element é um componente de IU para a Web que permite que você aceite mais de 100 formas de pagamento, valide a entrada e lide com erros. Use-o isoladamente ou com outros elementos no front-end do seu aplicativo da web. ## APIs compatíveis A Stripe oferece duas APIs principais do pagamentos compatíveis com o Elements. Recomendamos a [API Checkout Sessions](https://docs.stripe.com/api/checkout/sessions.md) para a maioria das integrações. - Use a [API Checkout Sessions](https://docs.stripe.com/api/checkout/sessions.md) para criar seu fluxo de checkout. O Checkout Sessions abrange casos de uso semelhantes ao Payment Intents, incluindo pagamentos básicos usando `price_data` ou checkout completo com itens de linha, tributos, descontos, envios, assinaturas ou [Adaptive Pricing](https://docs.stripe.com/payments/currencies/localize-prices/adaptive-pricing.md) (disponível apenas com Checkout Sessions). Crie uma página de checkout [com a API Checkout Sessions](https://docs.stripe.com/payments/quickstart-checkout-sessions.md). - A [API Payment Intents](https://docs.stripe.com/api/payment_intents.md) é uma API de nível inferior que modela apenas a etapa de pagamento. Você passa um valor final e cria você mesmo toda a lógica de Checkout, incluindo cálculo tributado, descontos, envios, assinaturas e conversão de moedas. Use Payment Intents somente se quiser ter um estado de Checkout próprio e criar esses recursos. Crie uma [integração personalizada do zero com a API Payment Intents](https://docs.stripe.com/payments/advanced.md). (See full diagram at https://docs.stripe.com/payments/payment-element) [Crie um integração avançada com Payment Element e Checkout Sessions](https://docs.stripe.com/payments/quickstart-checkout-sessions.md): Crie uma integração com o Payment Element usando a API Checkout Sessions. [Crie uma integração com o Payment Element e Payment Intents](https://docs.stripe.com/payments/quickstart.md): Use a API Payment Intents para criar seu próprio fluxo de checkout. [Clonar um exemplo de aplicativo no GitHub](https://github.com/stripe-samples/accept-a-payment/tree/main/payment-element) ## Combinar elementos O Payment Element interopera com outros elementos. Por exemplo, este formulário usa um elemento adicional para [preencher automaticamente os dados de checkout](https://docs.stripe.com/payments/link.md) e outro para [coletar o endereço de envio](https://docs.stripe.com/elements/address-element.md). > Você não pode remover o contrato jurídico do Link porque ele é necessário para garantir a conformidade e a conscientização adequada do usuário sobre os termos de serviço e as políticas de privacidade. O objeto [termos](https://docs.stripe.com/js/elements_object/create_payment_element#payment_element_create-options-terms) não se aplica ao contrato jurídico do Link. ![Um formulário com informações de contato, endereço de envio e campos de pagamento. As informações de contato são rotuladas como Link Authentication Element, o endereço de envio é rotulado como Address Element e os campos de pagamento são rotulados como Payment Element.](https://b.stripecdn.com/docs-statics-srv/assets/link-with-elements.f60af275f69b6e6e73c766d1f9928457.png) Formulário de pagamento combinando vários elementos Para o código completo deste exemplo, consulte [Adicionar Link a uma integração](https://docs.stripe.com/payments/link/add-link-elements-integration.md) com Elements. Também é possível combinar o Payment Element com o [Express Checkout Element](https://docs.stripe.com/elements/express-checkout-element.md). Neste caso, formas de pagamento de carteira, como Apple Pay e Google Pay, são exibidas somente no Express Checkout Element para evitar duplicidade. ## Formas de pagamento A Stripe habilita determinadas formas de pagamento para você por padrão. Também podemos habilitar formas de pagamento adicionais após notificar você. Use o [Dashboard](https://dashboard.stripe.com/settings/payment_methods) para habilitar ou desabilitar formas de pagamento a qualquer momento. Com o Payment Element, você pode usar [formas de pagamento dinâmicas](https://docs.stripe.com/payments/payment-methods/dynamic-payment-methods.md) para: - Gerencie formas de pagamento no [Dashboard](https://dashboard.stripe.com/settings/payment_methods) sem programar - Exiba dinamicamente as opções de pagamento mais relevantes com base em fatores como localização, moeda e valor da transação Por exemplo, se um cliente na Alemanha estiver pagando em EUR, ele verá todas as formas de pagamento ativas que aceitam EUR, começando pelas mais usadas na Alemanha. ![Várias formas de pagamento.](https://b.stripecdn.com/docs-statics-srv/assets/payment-element-methods.26cae03aff199d6f02b0d92bd324c219.png) Mostre as formas de pagamento em ordem de relevância para o cliente Para personalizar melhor a renderização das formas de pagamento, Se sua integração exigir que você liste formas de pagamento manualmente, consulte [Lista manualmente de formas de pagamento](https://docs.stripe.com/payments/payment-methods/integration-options.md#listing-payment-methods-manually). ## Layout Você pode personalizar o layout do Payment Element para se adequar ao seu fluxo de checkout. A imagem a seguir é o mesmo Payment Element processado usando diferentes configurações de layout. ![Exemplos dos três formulários de checkout. A imagem mostra a opção de guia, onde os clientes escolhem entre as formas de pagamento exibidas como guias ou as duas opções tipo sanfona, onde as formas de pagamento são listadas verticalmente. É possível escolher a exibição botões de seleção ou não na visualização tipo sanfona.](https://b.stripecdn.com/docs-statics-srv/assets/pe_layout_example.525f78bcb99b95e49be92e5dd34df439.png) Payment Element com diferentes layouts. #### Guias O layout das guias exibe as formas de pagamento horizontalmente usando guias. Para usar esse layout, defina o valor de [layout.type](https://docs.stripe.com/js/elements_object/create_payment_element#payment_element_create-options-layout-type) como `tabs`. Você também pode especificar outras propriedades, como [layout.defaultCollapsed](https://docs.stripe.com/js/elements_object/create_payment_element#payment_element_create-options-layout-defaultCollapsed). ```javascript const stripe = Stripe('<>'); const appearance = { /* appearance */ }; const options = { layout: { type: 'tabs', defaultCollapsed: false, } }; const elements = stripe.elements({ clientSecret, appearance }); // Em uma integração funcional, esse é um valor passado pelo seu backend com detalhes como o valor de um pagamento. Veja o exemplo completo para obter mais informações. const paymentElement = elements.create('payment', options); paymentElement.mount('#payment-element'); ``` #### Sanfona com botões de seleção O layout tipo sanfona exibe formas de pagamento verticalmente usando uma sanfona. Para usar esse layout, defina o valor de [layout.type](https://docs.stripe.com/js/elements_object/create_payment_element#payment_element_create-options-layout-type) como `accordion`. Você também pode especificar outras propriedades, como [layout.radios](https://docs.stripe.com/js/elements_object/create_payment_element#payment_element_create-options-layout-radios) para exibir botões de seleção. ```javascript const stripe = Stripe('<>'); const appearance = { /* appearance */ }; const options = { layout: { type: 'accordion', defaultCollapsed: false, radios: 'always', spacedAccordionItems: false } }; const clientSecret = {{CLIENT_SECRET}}; // Em uma integração funcional, esse é um valor passado pelo seu backend com detalhes como o valor de um pagamento. Veja o exemplo completo para obter mais informações. const elements = stripe.elements({ clientSecret, appearance }); const paymentElement = elements.create('payment', options); paymentElement.mount('#payment-element'); ``` #### Sanfona sem botões de seleção O layout tipo sanfona exibe formas de pagamento verticalmente usando uma sanfona. Para usar esse layout, defina o valor de [layout.type](https://docs.stripe.com/js/elements_object/create_payment_element#payment_element_create-options-layout-type) como `accordion`. Você também pode especificar outras propriedades, como [layout.spacedAccordionItems](https://docs.stripe.com/js/elements_object/create_payment_element#payment_element_create-options-layout-spacedAccordionItems) para criar espaço vertical adicional. ```javascript const stripe = Stripe('<>'); const appearance = { /* appearance */ }; const options = { layout: { type: 'accordion', defaultCollapsed: false, radios: 'never', spacedAccordionItems: true } }; const clientSecret = {{CLIENT_SECRET}}; // Em uma integração funcional, esse é um valor passado pelo seu backend com detalhes como o valor de um pagamento. Veja o exemplo completo para obter mais informações. const elements = stripe.elements({ clientSecret, appearance }); const paymentElement = elements.create('payment', options); paymentElement.mount('#payment-element'); ``` ## Aparência Use a API Appearance para controlar o estilo de todos os elementos. Escolha um tema ou atualize detalhes específicos. ![Exemplos de modos claro e escuro para o formulário de checkout do Payment Element.](https://b.stripecdn.com/docs-statics-srv/assets/appearance_example.e076cc750983bf552baf26c305e7fc90.png) Por exemplo, escolha o tema “plano” e sobreponha a cor principal do texto. ```javascript const stripe = Stripe('<>'); const appearance = { theme: 'flat', variables: { colorPrimaryText: '#262626' } }; const options = { /* options */ }; const elements = stripe.elements({ clientSecret, appearance }); // Em uma integração funcional, esse é um valor passado pelo seu backend com detalhes como o valor de um pagamento. Veja o exemplo completo para obter mais informações. const paymentElement = elements.create('payment', options); paymentElement.mount('#payment-element'); ``` Consulte a documentação da [API Appearance](https://docs.stripe.com/elements/appearance-api.md) para obter uma lista completa de temas e variáveis. ## Opções Os elementos da Stripe aceitam mais opções do que essas. Por exemplo, exiba o nome da sua empresa usando a opção [business](https://docs.stripe.com/js/elements_object/create_payment_element#payment_element_create-options-business). ```javascript const stripe = Stripe('<>'); const appearance = { /* appearance */}; const options = { business: { name: "RocketRides" } }; const clientSecret = {{CLIENT_SECRET}}; // Em uma integração funcional, esse é um valor passado pelo seu backend com detalhes como o valor de um pagamento. Veja o exemplo completo para obter mais informações. const elements = stripe.elements(appearance, clientSecret); const paymentElement = elements.create('payment', options); paymentElement.mount('#payment-element'); ``` O Payment Element aceita as seguintes opções. Veja a referência de cada opção para obter mais informações. | | | | | [layout](https://docs.stripe.com/js/elements_object/create_payment_element#payment_element_create-options-layout) | Layout para o Payment Element. | | [defaultValues](https://docs.stripe.com/js/elements_object/create_payment_element#payment_element_create-options-defaultValues) | Dados iniciais do cliente a serem exibidos no Payment Element. | | [business](https://docs.stripe.com/js/elements_object/create_payment_element#payment_element_create-options-business) | Informações sobre sua empresa a serem exibidas no Payment Element. | | [paymentMethodOrder](https://docs.stripe.com/js/elements_object/create_payment_element#payment_element_create-options-business) | Ordem para listar formas de pagamento. | | [campos](https://docs.stripe.com/js/elements_object/create_payment_element#payment_element_create-options-fields) | Exibir ou não determinados campos. | | [readOnly](https://docs.stripe.com/js/elements_object/create_payment_element#payment_element_create-options-readOnly) | Se os detalhes do pagamento podem ser alterados. | | [terms](https://docs.stripe.com/js/elements_object/create_payment_element#payment_element_create-options-terms) | Se mandatos ou outros contratos legais forem exibidos no Payment Element. O comportamento padrão é mostrá-los somente quando necessário. | | [wallets](https://docs.stripe.com/js/elements_object/create_payment_element) | Mostrar ou não carteiras como Apple Pay ou Google Pay. O padrão é mostrá-los quando possível. | ## Erros O Payment Element mostra automaticamente mensagens de erro traduzidas para o cliente durante a confirmação do cliente para os seguintes códigos de pagamento recusado: - `card_declined` - `card_velocity_exceeded` - `expired_card` - `fraudulent` - `generic_decline` - `incorrect_cvc` - `incorrect_number` - `incorrect_zip` - `insufficient_funds` - `invalid_cvc` - `invalid_expiry_month` - `invalid_expiry_year` - `live_mode_test_card` - `lost_card` - `processing_error` - `stolen_card` - `test_mode_live_card` Para exibir mensagens para outros tipos de erros, consulte [códigos de erro](https://docs.stripe.com/error-codes.md) e [gerenciamento de erros](https://docs.stripe.com/error-handling.md).