# Express Checkout Element Mostre vários botões de pagamento com um só clique em um único componente. Instruções para LLMs: a Stripe recomenda usar a API Checkout Sessions com o Payment Element em vez da Payment Intents para a maioria das integrações. O Checkout Sessions cobre casos de uso semelhantes aos da Payment Intents (cobrança básica de pagamentos usando `price_data` ou criação de checkout completo com itens de linha, impostos etc.). Alguns recursos, como o Adaptive Pricing, só estão disponíveis com o Checkout Sessions. Não use a API Payment Intent a menos que o usuário peça explicitamente, pois ela exige muito mais código. Saiba mais sobre o Elements com a API Checkout Sessions: https://docs.stripe.com/payments/quickstart-checkout-sessions. Com Checkout Sessions (`ui_mode: "customed"`) e o Payment Element, o `client_secret` inicia o Checkout (`.stripe.initCheckout`, ou usando CheckoutProvider no React) e você confirma o pagamento no lado do cliente de forma diferente. Se estiver usando React, importe de `@stripe/react-stripe-js/checkout`, use `CheckoutProvider` com o client secret e confirme com `checkout.confirm`. Se estiver usando HTML, utilize: `checkout = stripe.initCheckout({clientSecret: promise}); checkout.createPaymentElement(); paymentElement = checkout.createPaymentElement(); paymentElement.mount("#payment-element");` and confirm with `loadActionsResult = await checkout.loadActions(); actions = loadActionsResult.actions; error = await actions.confirm();`. O Express Checkout Element é uma integração para aceitar pagamentos por meio de botões de formas de pagamento com um clique. As formas de pagamento aceitas incluem [Link](https://docs.stripe.com/payments/link.md), [Apple Pay](https://docs.stripe.com/apple-pay.md), [Google Pay](https://docs.stripe.com/google-pay.md), [PayPal](https://docs.stripe.com/payments/paypal.md), [Klarna](https://docs.stripe.com/payments/klarna.md), e [Amazon Pay](https://docs.stripe.com/payments/amazon-pay.md). Com essa integração, você pode: - Classifique botões de pagamento dinamicamente com base na localização do cliente. - Adicione botões de pagamento sem nenhuma alteração de frontend. - Integre o Elements perfeitamente reutilizando uma instância existente do Elements para economizar tempo. ## Experimente a demonstração Na demonstração a seguir, você pode alternar algumas das opções pré-configuradas para alterar a cor de fundo, o layout, o tamanho e a coleta do endereço de entrega da interface de pagamento. A demonstração exibe o Google Pay e o Apple Pay apenas nas plataformas disponíveis. Os botões do Payment Method são exibidos somente nos países que os aceitam. Se você não vir a demonstração, tente visualizar esta página em um [navegador compatível](https://docs.stripe.com/elements/express-checkout-element.md#supported-browsers). | Opção | Descrição | | ----------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **País do comerciante** | Defina isso usando a [chave publicável](https://docs.stripe.com/keys.md#obtain-api-keys) usada para [inicializar o Stripe.js](https://docs.stripe.com/js/initializing). Para alterar o país, desmonte o Express Checkout Element, atualize a chave publicável e remonte o Express Checkout Element. | | **Cor de fundo** | Defina cores usando a [API Elements Appearance](https://docs.stripe.com/elements/appearance-api.md). Os temas de botão são herdados da API Appearance, mas você também pode [defini-los diretamente ao criar o Element](https://docs.stripe.com/js/elements_object/create_express_checkout_element#express_checkout_element_create-options-buttonTheme). | | **Tamanho para desktops e dispositivos móveis** | Use a lista suspensa para definir a largura máxima em pixels do elemento principal no qual o Express Checkout Element está montado. Você pode defini-lo como 750px (desktop) ou 320px (Mobile). | | **Máximo de colunas e máximo de linhas** | Defina esses valores usando o parâmetro [layout](https://docs.stripe.com/js/elements_object/create_express_checkout_element#express_checkout_element_create-options-layout) ao [criar o Express Checkout Element](https://docs.stripe.com/js/elements_object/create_express_checkout_element). | | **Menu de navegação** | Defina isso usando o parâmetro [layout](https://docs.stripe.com/js/elements_object/create_express_checkout_element#express_checkout_element_create-options-layout) ao [criar o Express Checkout Element](https://docs.stripe.com/js/elements_object/create_express_checkout_element). | | **Coletar endereço de entrega** | Para coletar dados de envio, você deve passar opções ao [criar](https://docs.stripe.com/js/elements_object/create_express_checkout_element) o Express Checkout Element. Saiba mais sobre [coletar dados do cliente e exibir itens de linha](https://docs.stripe.com/elements/express-checkout-element/accept-a-payment.md#handle-create-event). | ## Começar com um guia [Adicione carteiras digitais de um clique à sua página de checkout](https://docs.stripe.com/elements/express-checkout-element/accept-a-payment.md): Crie uma integração com o Express Checkout Element usando a API Checkout Sessions. [Use carteiras digitais com um clique em integrações avançadas](https://docs.stripe.com/elements/express-checkout-element/accept-a-payment.md?payment-ui=elements): Crie uma integração com o Express Checkout Element usando a API Payment Intents. [Migrar para o Express Checkout Element](https://docs.stripe.com/elements/express-checkout-element/migration.md): Migre do Payment Request Button Element para o Checkout Express Element da web. ## Formas de pagamento O Express Checkout Element apresenta formas de pagamento de um clique que são ativas, aceitas e configuradas. - Algumas formas de pagamento [exigem ativação no Dashboard](https://dashboard.stripe.com/settings/payment_methods). - As formas de pagamento só estão disponíveis quando o cliente usa um navegador aceito e paga em uma moeda aceita. - Algumas formas de pagamento exigem ações de configuração por parte do cliente. Por exemplo, um cliente não verá o botão do Google Pay se não tiver o Google Pay configurado. - [Registre seu domínio](https://docs.stripe.com/payments/payment-methods/pmd-registration.md) no seu ambiente de testes e no modo de produção. O elemento classifica as formas de pagamento por relevância para seu cliente. Para controlar esses comportamentos, você pode [personalizar as formas de pagamento](https://docs.stripe.com/elements/express-checkout-element.md#customize-payment-methods). ## Navegadores aceitos Determinadas formas de pagamento funcionam com navegadores específicos. | | Apple Pay | Google Pay | Link | PayPal | Amazon Pay | Klarna | | ------------------------ | ------------- | ------------ | ------------- | ------------- | ------------- | ------------- | | Chrome1 | ✓ Aceito3 | ✓ Aceitos | ✓ Aceitos | ✓ Aceitos | ✓ Aceitos | ✓ Aceitos | | Edge | ✓ Aceito3 | ✓ Aceitos | ✓ Aceitos | ✓ Aceitos | ✓ Aceitos | ✓ Aceitos | | Firefox | ❌ Não aceitos | ✓ Supported5 | ❌ Não aceitos | ✓ Aceitos | ✓ Aceitos | ❌ Não aceitos | | Opera | ✓ Aceito3 | ✓ Aceitos | ✓ Aceitos | ✓ Aceitos | ✓ Aceitos | ✓ Aceitos | | Safari | ✓ Supported2 | ✓ Aceito4 | ✓ Aceitos | ✓ Aceitos | ✓ Aceitos | ✓ Aceitos | | Chrome no iOS 16 ou mais | ✓ Aceitos | ✓ Aceitos | ✓ Aceitos | ✓ Aceitos | ✓ Aceitos | ✓ Aceitos | | Firefox no iOS 16+ | ✓ Aceitos | ✓ Aceitos | ✓ Aceitos | ❌ Não aceitos | ❌ Não aceitos | ❌ Não aceitos | | Edge no iOS 16+ | ✓ Aceitos | ✓ Aceitos | ❌ Não aceitos | ❌ Não aceitos | ❌ Não aceitos | ❌ Não aceitos | 1Outros navegadores Chromium podem ser aceitos. Para obter mais informações, consulte [navegadores aceitos](https://docs.stripe.com/js/appendix/supported_browsers). 2Quando usar um iframe, sua origem precisa corresponder à origem de nível superior (exceto Safari 17+ quando especificar o atributo `allow="payment"`). Duas páginas têm a mesma origem se o protocolo, host (nome completo do domínio) e porta (se especificada) forem os mesmos para ambas as páginas. 3O Apple Pay nos navegadores Chromium para desktop só são aceitos no MacOS quando [paymentMethods.applePay](https://docs.stripe.com/js/elements_object/create_express_checkout_element#express_checkout_element_create-options-paymentMethods-applePay) está definido como `always`. 4O Google Pay em navegadores Safari só é aceito quando [paymentMethods.googlePay](https://docs.stripe.com/js/elements_object/create_express_checkout_element#express_checkout_element_create-options-paymentMethods-googlePay) está definido como `always`. 5O Google Pay em navegadores Firefox só é aceito quando [paymentMethods.googlePay](https://docs.stripe.com/js/elements_object/create_express_checkout_element#express_checkout_element_create-options-paymentMethods-googlePay) está definido como `always`. > O Express Checkout Element tem suporte limitado em visualizações web dentro de aplicativos. Muitas formas de pagamento exigem janelas pop-up e podem não funcionar corretamente. Para integrações em aplicativos móveis, considere usar o [iOS SDK](https://docs.stripe.com/payments/accept-a-payment.md?payment-ui=mobile&platform=ios) ou [Android SDK](https://docs.stripe.com/payments/accept-a-payment.md?payment-ui=mobile&platform=android)… ## Layout Por padrão, quando o Express Checkout Element exibe vários botões, ele organiza os botões em uma grade com base no espaço disponível e exibe um menu de navegação, se necessário. Você pode substituir esse padrão e especificar um layout de grade por conta própria com a opção [layout](https://docs.stripe.com/js/elements_object/create_express_checkout_element#express_checkout_element_create-options-layout). ## Texto Você pode controlar o texto de um botão selecionando um [buttonType](https://docs.stripe.com/js/elements_object/create_express_checkout_element#express_checkout_element_create-options-buttonType). Cada carteira oferece seus próprios tipos. #### Link O Link oferece apenas um tipo de botão, que apresenta a chamada para ação “Pagar com Link” e o logotipo do Link. Tentamos detectar a localização do seu cliente e usá-la para localizar o texto do botão. Você também pode especificar uma [localidade](https://docs.stripe.com/js/elements_object/create#stripe_elements-options-locale). #### Apple Pay Os tipos de botão Apple Pay apresentam diferentes chamadas à ação ao lado do logotipo Apple Pay. Tentamos detectar a localização do seu cliente e passá-la para a Apple para que ele localize o texto do botão. Você também pode especificar uma [localidade](https://docs.stripe.com/js/elements_object/create#stripe_elements-options-locale). Aceitamos os seguintes tipos de botão Apple Pay. | Tipo de botão | Chamada para ação | | ------------- | ------------------------- | | `plain` | Nenhum, apenas o logotipo | | `add-money` | “Adicione dinheiro com” | | `book` | “Reservar com” | | `buy` | “Comprar com” | | `check-out` | “Fazer checkout com” | | `contribute` | “Contribuir com” | | `donate` | “Doar com” | | `order` | “Pedir com” | | `reload` | “Recarregar com” | | `rent` | “Alugar com” | | `subscribe` | “Assinar com” | | `support` | “Aceitar com” | | `tip` | “Dar gorjeta com” | | `top-up` | “Recarregar com” | #### Google Pay Os tipos de botão do Google Pay apresentam diferentes chamadas à ação ao lado do logotipo do Google Pay. Tentamos detectar a localização do seu cliente e passá-la ao Google Pay para que ele localize o texto do botão. Você também pode especificar uma [localidade](https://docs.stripe.com/js/elements_object/create#stripe_elements-options-locale). Aceitamos os seguintes tipos de botão do Google Pay. | Tipo de botão | Chamada para ação | | ------------- | ------------------------- | | `plain` | Nenhum, apenas o logotipo | | `book` | “Reservar com” | | `buy` | “Comprar com” | | `checkout` | “Fazer checkout com” | | `donate` | “Doar com” | | `order` | “Pedir com” | | `pay` | “Pagar com” | | `subscribe` | “Assinar com” | #### PayPal Tipos de botão do PayPal apresentam diferentes chamadas à ação ao lado do logotipo do PayPal. Tentamos detectar a localização do seu cliente e passá-la para o PayPal para que ele localize o texto do botão. Você também pode especificar uma [localidade](https://docs.stripe.com/js/elements_object/create#stripe_elements-options-locale). Aceitamos os seguintes tipos de botão do PayPal. | Tipo de botão | Chamada para ação | | ------------- | ------------------------- | | `paypal` | Nenhum, apenas o logotipo | | `checkout` | “Checkout” | | `buynow` | “Comprar agora” | | `pay` | “Pagar com” | #### Amazon Pay O Amazon Pay oferece apenas um tipo de botão, que apresenta o logotipo do Amazon Pay sem uma chamada para ação. #### Klarna Os tipos de botão Klarna apresentam diferentes ações ao lado do logotipo Klarna. Tentamos detectar a localização do seu cliente e repassá-la ao Klarna para localizar o texto do botão. Também é possível especificar uma [localização](https://docs.stripe.com/js/elements_object/create#stripe_elements-options-locale). Aceitamos os tipos de botão Klarna a seguir. | | | | | `continue` | “Continuar com” | | `pay` | “Pagar com” | Este exemplo de código inclui uma chamada para ação “Compre” ou “Compre agora” para botões compatíveis. Em seguida, especifica o local `de` para obter seus equivalentes em alemão. ```js const expressCheckoutOptions = { buttonType: { applePay: 'buy', googlePay: 'buy', paypal: 'buynow', klarna: 'pay', } } const elements = stripe.elements({ locale: 'de', mode: 'payment', amount: 1099, currency: 'usd', }) const expressCheckoutElement = elements.create( 'expressCheckout', expressCheckoutOptions ) expressCheckoutElement.mount('#express-checkout-element') ``` ## Aparência Não é possível personalizar totalmente a aparência dos botões do Express Checkout Element porque cada forma de pagamento define seu próprio logotipo e cores da marca. Você pode personalizar as seguintes opções: - [Altura do botão](https://docs.stripe.com/js/elements_object/create_express_checkout_element#express_checkout_element_create-options-buttonHeight) - Raio da borda usando variáveis com a API [Appearance](https://docs.stripe.com/elements/appearance-api.md) - [Temas do botão](https://docs.stripe.com/js/elements_object/create_express_checkout_element#express_checkout_element_create-options-buttonTheme) > O botão Apple Pay é redimensionado automaticamente quando o raio de borda aumenta para além de um determinado limite. Se estiver modificando o raio de borda padrão, teste-o com todas as formas de pagamento ativas. Este exemplo de código configura um grupo de elementos com um tema claro e um raio de borda de 36 pixels, cria botões com 50 pixels de altura e substitui o tema para usar a versão com contorno branco do botão Apple Pay . ```js const appearance = { theme: 'stripe', variables: { borderRadius: '36px', } } const expressCheckoutOptions = { buttonHeight: 50, buttonTheme: { applePay: 'white-outline' } } const elements = stripe.elements({ mode: 'payment', amount: 1099, currency: 'usd', appearance, }) const expressCheckoutElement = elements.create( 'expressCheckout', expressCheckoutOptions ) expressCheckoutElement.mount('#express-checkout-element') ``` Aceitamos os seguintes temas: #### Link O Link tem um tema de botão único, que pode ser lido em um fundo claro ou escuro. #### PayPal O PayPal tem vários temas de botões. Se você definir um tema com a API [Appearance](https://docs.stripe.com/elements/appearance-api.md), o Express Checkout Element escolhe um tema compatível para o botão do PayPal. Por exemplo, se você especificar um fundo escuro, escolhemos um tema de botão claro para visibilidade. Você também pode escolher um tema com a opção [buttonTheme.paypal](https://docs.stripe.com/js/elements_object/create_express_checkout_element#express_checkout_element_create-options-buttonTheme-paypal). Consulte o [guia de estilo dos botões](https://developer.paypal.com/docs/multiparty/checkout/standard/customize/buttons-style-guide/) para obter imagens atualizadas e orientações sobre como usá-las. Aceitamos os seguintes valores: | | | | | `gold` | Cores da marca ouro e azul do PayPal | | `blue` | Cor azul sólida da marca do PayPal | | `silver` | Logotipo do PayPal em um fundo prateado | | `white` | Logotipo do PayPal em um fundo branco | | `black` | Logotipo do PayPal em um fundo preto | #### Apple Pay O Apple Pay tem vários temas de botões. Se você definir um tema com a API [Appearance](https://docs.stripe.com/elements/appearance-api.md), o Express Checkout Element escolhe um tema compatível para o botão do Apple Pay. Por exemplo, se você especificar um fundo escuro, escolhemos um tema de botão claro para visibilidade. Também é possível escolher um tema com a opção [ButtonTheme.applePay](https://docs.stripe.com/js/elements_object/create_express_checkout_element#express_checkout_element_create-options-buttonTheme-applePay). Consulte o [guia de estilo do botão](https://developer.apple.com/design/human-interface-guidelines/apple-pay#Using-Apple-Pay-buttons) do Apple Pay para ver imagens atualizadas e orientações sobre como usá-las. Aceitamos os seguintes valores: | | | | | `black` | Um fundo preto com texto branco | | `white` | Um fundo branco com texto em preto | | `white-outline` | Um fundo branco com texto preto e uma borda preta | #### Google Pay O Google Pay tem vários temas de botão. Se você definir um tema com a API [Appearance](https://docs.stripe.com/elements/appearance-api.md), o Express Checkout Element escolhe um tema compatível para o botão do Google Pay. Por exemplo, se você especificar um fundo escuro, escolhemos um tema de botões claro para dar visibilidade. Você também pode escolher um tema com a opção [buttonTheme.googlePay](https://docs.stripe.com/js/elements_object/create_express_checkout_element#express_checkout_element_create-options-buttonTheme-googlePay). Consulte as [diretrizes da marca Google Pay](https://developers.google.com/pay/api/web/guides/brand-guidelines) para obter imagens atualizadas e orientações sobre como usá-las. Aceitamos os seguintes valores: | | | | | `black` | Um fundo preto com texto branco | | `white` | Um fundo branco com texto em preto | #### Amazon Pay O Amazon Pay tem um tema de botão único. #### Klarna O Klarna tem vários temas de botão. Se você definir um tema com a API [Appearance](https://docs.stripe.com/elements/appearance-api.md), o Express Checkout Element escolhe um tema compatível para o botão Klarna. Por exemplo, se você especificar um fundo escuro, escolhemos um tema de botões claro para dar visibilidade. Também é possível escolher um tema com a opção [ButtonTheme.klarna](https://docs.stripe.com/js/elements_object/create_express_checkout_element#express_checkout_element_create-options-buttonTheme-klarna). ## Personalizar formas de pagamento Você não pode especificar quais formas de pagamento exibir. Por exemplo, não é possível forçar a exibição de um botão do Google Pay se o dispositivo do cliente não for compatível com o Google Pay. No entanto, você pode personalizar o comportamento da forma de pagamento de várias maneiras, como: - Você pode ativar ou desativar formas de pagamento no [Dashboard](https://dashboard.stripe.com/settings/payment_methods). - Você pode sobrepor a lógica padrão da Stripe de classificação das formas de pagamento por relevância. Use a opção [paymentMethodOrder](https://docs.stripe.com/js/elements_object/create_express_checkout_element#express_checkout_element_create-options-paymentMethodOrder) para definir seu pedido preferencial. - Se houver pouco espaço no layout, formas de pagamento de baixa relevância podem aparecer em um menu de navegação. Personalize quando o menu aparece usando a opção [layout](https://docs.stripe.com/js/elements_object/create_express_checkout_element#express_checkout_element_create-options-layout). - Para evitar que o Apple Pay ou o Google Pay apareçam, defina [paymentMethods.applePay](https://docs.stripe.com/js/elements_object/create_express_checkout_element#express_checkout_element_create-options-paymentMethods-applePay) ou [paymentMethods.googlePay](https://docs.stripe.com/js/elements_object/create_express_checkout_element#express_checkout_element_create-options-paymentMethods-applePay) como `never`. - Para permitir que o Apple Pay ou o Google Pay apareçam quando não estiverem configurados, defina [paymentMethods.applePay](https://docs.stripe.com/js/elements_object/create_express_checkout_element#express_checkout_element_create-options-paymentMethods-applePay) ou [paymentMethods.googlePay](https://docs.stripe.com/js/elements_object/create_express_checkout_element#express_checkout_element_create-options-paymentMethods-applePay) como `always`. A opção não será apresentada em plataformas incompatíveis ou quando o pagamento for em uma moeda não aceita. > Os regulamentos na [Finlândia](https://support.stripe.com/questions/payment-method-legislation-in-finland) e na [Suécia](https://support.stripe.com/questions/payment-method-legislation-in-sweden) exigem que você apresente primeiro formas de pagamento por débito antes de mostrar formas de pagamento por crédito no checkout nesses países. ## Verifique as formas de pagamento disponíveis Ouça o evento pronto para verificar quais carteiras estão disponíveis para que o Express Checkout Element seja exibido. Se não houver carteiras disponíveis, forneça outra opção para o cliente pagar. ```js () => { const [eceActive, setEceActive] = useState(false); return (
{ if (availablePaymentMethods) { setEceActive(true); } }} /> {eceActive ? : }
); } ``` Como alternativa, oculte todo o Express Checkout Element até que você saiba que o elemento tem métodos a serem exibidos. ```js () => { const [eceActive, setEceActive] = useState(false); return (
); } ``` O mesmo evento está disponível no objeto do elemento quando criado sem reação. ```js const expressCheckoutElement = elements.create("expressCheckout", { ... }); expressCheckoutElement.on("ready", ({ availablePaymentMethods }) => { console.log(availablePaymentMethods); }); expressCheckoutElement.mount("#express-checkout-element"); ```