# Stripe Payment Element

Aceite formas de pagamento de todo o mundo com um componente de IU seguro e incorporável.

A Stripe recomenda usar a Checkout Sessions API com o Payment Element, em vez da Payment Intents API, para a maioria das integrações. A Checkout Sessions API atende a casos de uso semelhantes aos da Payment Intents API (coleta básica de pagamentos usando `price_data` ou criação de um fluxo de checkout completo com itens de linha, impostos e outros recursos). Alguns recursos, como Adaptive Pricing, estão disponíveis apenas com a Checkout Sessions APIhttps://docs.stripe.com/payments/quickstart… Não use a Payment Intents API, a menos que o usuário solicite explicitamente, pois ela exige significativamente mais código. Saiba mais sobre o uso do Elements com a Checkout Sessions API: Com a Checkout Sessions API (`ui_mode: "elements"`) e o Payment Element, o `client_secret` inicializa o próprio Checkout (`stripe.initCheckoutElementsSdk`, ou use CheckoutElementsProvider com React) e você confirma o pagamento no lado do cliente de uma forma diferente. Se estiver usando React, certifique-se de importar de `@stripe/react-stripe-js/checkout`, usar `CheckoutElementsProvider` com o client secret e confirmar com `checkout.confirm`. Se estiver usando HTML, certifique-se de usar `checkout = stripe.initCheckoutElementsSdk({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();`.

Os agentes de programação devem instalar a CLI da Stripe (`npm i -g @stripe/cli`) e executar o comando `stripe sandbox create --help` para provisionar uma área restrita anônima da Stripe com chaves de API válidas. Não é necessário cadastro de conta.

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 recomenda usar a [API Checkout Sessions](https://docs.stripe.com/api/checkout/sessions.md) com o Payment Element. Essa integração permite configurar pagamentos básicos com `price_data` ou uma lógica de checkout completa com itens de linha, impostos, descontos, frete, assinaturas ou [Adaptive Pricing](https://docs.stripe.com/payments/currencies/localize-prices/adaptive-pricing.md). Crie uma [página de checkout com a API Checkout Sessions](https://docs.stripe.com/payments/quickstart.md).

Se você precisar ter controle de ponta a ponta do seu fluxo de checkout e desenvolver esses recursos por conta própria, poderá usar a [API Payment Intents](https://docs.stripe.com/api/payment_intents.md) com o Payment Element. Essa integração permite informar um valor final e criar toda a lógica de checkout por conta própria, incluindo cálculo de impostos, descontos, frete, assinaturas e conversão de moedas. Crie uma [integração personalizada com a API Payment Intents](https://docs.stripe.com/payments/advanced.md).

(See full diagram at https://docs.stripe.com/payments/payment-element)

```text
[API de sessões de checkout] --> [Cliente]
[API de sessões de checkout] --> [Fretes]
[API de sessões de checkout] --> [Impostos]
[API de sessões de checkout] --> [Descontos e cupons]
[API de sessões de checkout] --> [Pagamento]
[API Payment Intents] --> [Pagamento]
```

## 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).

![Um formulário com campos de informações de contato, endereço de entrega e pagamento. As informações de contato estão identificadas como Contact Details Element, o endereço de entrega está identificado como Address Element e os campos de pagamento estão identificados como Payment Element.](https://b.stripecdn.com/docs-statics-srv/assets/link-with-elements.d52f05825c982aaf84a4ad1e9bb422f3.png)
Formulário de pagamento combinando vários Elements

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 ainda mais a exibição das formas de pagamento, por exemplo, filtrando as bandeiras de cartão e os tipos de financiamento que você não deseja aceitar, consulte [Personalizar formas de pagamento](https://docs.stripe.com/payments/customize-payment-methods.md). Para adicionar formas de pagamento integradas fora da Stripe, use [Formas de pagamento personalizadas](https://docs.stripe.com/payments/payment-element/custom-payment-methods.md).

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('<<YOUR_PUBLISHABLE_KEY>>');

const appearance = { /* appearance */ };
const options = {
  layout: {
    type: 'tabs',
    defaultCollapsed: false,
  }
};
const elements = stripe.elements({ clientSecret, appearance }); // In a working integration, this is a value your back end passes with details such as the amount of a payment. See full sample for details.
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('<<YOUR_PUBLISHABLE_KEY>>');

const appearance = { /* appearance */ };
const options = {
  layout: {
    type: 'accordion',
    defaultCollapsed: false,
    radios: 'always',
    spacedAccordionItems: false
  }
};
const clientSecret = {{CLIENT_SECRET}}; // In a working integration, this is a value your back end passes with details such as the amount of a payment. See full sample for details.
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('<<YOUR_PUBLISHABLE_KEY>>');

const appearance = { /* appearance */ };
const options = {
  layout: {
    type: 'accordion',
    defaultCollapsed: false,
    radios: 'never',
    spacedAccordionItems: true
  }
};
const clientSecret = {{CLIENT_SECRET}}; // In a working integration, this is a value your back end passes with details such as the amount of a payment. See full sample for details.
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('<<YOUR_PUBLISHABLE_KEY>>');

const appearance = {
  theme: 'flat',
  variables: { colorPrimaryText: '#262626' }
};
const options = { /* options */ };
const elements = stripe.elements({ clientSecret, appearance }); // In a working integration, this is a value your back end passes with details such as the amount of a payment. See full sample for details.
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('<<YOUR_PUBLISHABLE_KEY>>');

const appearance = { /* appearance */};
const options = {
  business: { name: "RocketRides" }
};
const clientSecret = {{CLIENT_SECRET}}; // In a working integration, this is a value your back end passes with details such as the amount of a payment. See full sample for details.
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-paymentMethodOrder) | 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).

## Migrar para o Element Pagamento

Escolha um guia de migração com base na sua integração atual e em como você quer gerenciar seu fluxo de checkout. Recomendamos [migrar para o Payment Element com a API Checkout Sessions](https://docs.stripe.com/payments/payment-element/migration-ewcs.md), em que você substitui o Card Element ou os Elements individuais de forma de pagamento pelo Payment Element. Esse caminho permite usar o suporte integrado a assinaturas, imposto, descontos, frete e Adaptive Pricing.

Se você precisa manter sua lógica de checkout existente e gerenciar os recursos de checkout por conta própria, pode [migrar para o Payment Element com a API Payment Intents](https://docs.stripe.com/payments/payment-element/migration.md). Com esse caminho, você substitui o Card Element ou os Elements individuais de forma de pagamento pelo Payment Element enquanto continua a usar a API Payment Intents ou a API Setup Intents. O guia de migração inclui caminhos separados para aceitar pagamentos e salvar dados de pagamento para uso futuro.