# Aceitar um pagamento Aceitar pagamentos online com segurança ## Comece aqui: instale skills de agente A Stripe recomenda usar skills oficiais para integrar com a API seguindo práticas recomendadas. Siga as instruções abaixo para saber como. **Dica: use curl em vez de ferramentas Fetch.** Skills são arquivos markdown detalhados de 10 KB a 20 KB. Ferramentas Fetch fazem um resumo deles. `curl -sL` garante o conteúdo completo. **Usando `npx skills`**: verifique se `npx` está instalado no sistema. Se `npx` estiver disponível, execute `npx skills add https://docs.stripe.com --list` para listar os skills disponíveis e, depois, execute `npx skills add https://docs.stripe.com --yes --skill <--skill other-skills>` para instalar skills individuais. **Se `npx skills` não estiver disponível**: é possível usar curl para buscar o índice de skills disponíveis, o que eles fazem e seus arquivos em `https://docs.stripe.com/.well-known/skills/index.json`. Para baixar um skill e os arquivos relacionados, use curl para baixá-los de `https://docs.stripe.com/.well-known/skills/`. Para este artigo, recomendamos usar estes skills: `stripe-best-practices` 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();`. 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. Crie um formulário de pagamento ou use uma página de checkout pré-integrada para começar a aceitar pagamentos online. # API de Checkout Sessions Crie um formulário de pagamento personalizado usando o [Stripe Elements](https://docs.stripe.com/payments/elements.md) e a API de [Checkout Sessions](https://docs.stripe.com/api/checkout/sessions.md). Veja como essa integração [se compara aos outros tipos de integração](https://docs.stripe.com/payments/online-payments.md#compare-features-and-availability) da Stripe. A API de Checkout Sessions fornece suporte integrado para cálculo tributário, descontos, envio e conversão de moedas, reduzindo a quantidade de código personalizado que você precisa escrever. Essa é a abordagem recomendada para a maioria das integrações. Saiba mais sobre [quando usar Checkout Sessions em vez de PaymentIntents](https://docs.stripe.com/payments/checkout-sessions-and-payment-intents-comparison.md). O código do lado do cliente e do lado do servidor cria um formulário de Checkout que aceita várias formas de pagamento. #### Esforço de integração Complexity: 3/5 #### Tipo de integração Combine componentes de IU em um fluxo de pagamento personalizado #### Personalização da IU Personalização no nível de CSS com a [API Appearance](https://docs.stripe.com/elements/appearance-api.md) ## Configure o servidor [Lado do servidor] Antes de começar, você precisa [se cadastrar](https://dashboard.stripe.com/register) para uma conta Stripe. Use as bibliotecas Stripe oficiais para acessar o API do 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 uma sessão do Checkout [Lado do servidor] Adicione um endpoint no seu servidor que crie uma [Sessão de Checkout](https://docs.stripe.com/api/checkout/sessions/create.md) e retorne seu [`client_secret`](https://docs.stripe.com/api/checkout/sessions/object.md#checkout_session_object-client_secret) para o seu front-end. Uma Sessão de Checkout representa a sessão do seu cliente enquanto ele paga por compras únicas ou assinaturas. As sessões de checkout vencem 24 horas após sua criação. ```curl curl https://api.stripe.com/v1/checkout/sessions \ -u "<>:" \ -d ui_mode=elements \ -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]=2000" \ -d "line_items[0][quantity]=1" \ -d mode=payment \ --data-urlencode "return_url=https://example.com/return?session_id={CHECKOUT_SESSION_ID}" ``` ## Configurar o frontend [Lado do cliente] #### HTML + JS Inclua o script Stripe.js na página de checkout, adicionando-o ao `head` do seu arquivo HTML. Sempre carregue o Stripe.js diretamente a partir do js.stripe.com para manter a conformidade com PCI. Não insira o script em um pacote nem hospede sua própria cópia. Certifique-se de estar usando a versão mais recente de Stripe.js. Saiba mais sobre o [versionamento de Stripe.js](https://docs.stripe.com/sdks/stripejs-versioning.md). ```html Checkout ``` > A Stripe fornece um pacote npm que você pode usar para carregar o Stripe.js como um módulo. Veja o [projeto no GitHub](https://github.com/stripe/stripe-js). A versão [7.0.0](https://www.npmjs.com/package/%40stripe/stripe-js/v/7.0.0) ou posterior é necessária. Inicialize o Stripe.js. ```js // 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( '<>', ); ``` #### React Instale o [React Stripe.js](https://www.npmjs.com/package/@stripe/react-stripe-js) e o[carregador Stripe.js](https://www.npmjs.com/package/@stripe/stripe-js) do registro público do npm. Você precisa de pelo menos a versão 5.0.0 do React Stripe.js e a versão 8.0.0 do carregador Stripe.js. ```bash npm install --save @stripe/react-stripe-js @stripe/stripe-js ``` Inicialize uma instância de `stripe` no frontend com sua chave publicável. ```javascript import {loadStripe} from '@stripe/stripe-js'; const stripe = loadStripe("<>"); ``` ## Inicializar o Checkout [Lado do cliente] #### HTML + JS Chame [initCheckoutElementsSdk](https://docs.stripe.com/js/custom_checkout/init), passando o `clientSecret`. `initCheckoutElementsSdk` retorna um objeto [Checkout](https://docs.stripe.com/js/custom_checkout) que contém dados da Checkout Session e métodos para atualizá-lo. Leia o `total` e `lineItems` de [actions.getSession()](https://docs.stripe.com/js/custom_checkout/session), e exibi-os na sua IU. Isso permite ativar novos recursos com mínimas alterações no código. Por exemplo, somando [preços de moeda manual](https://docs.stripe.com/payments/custom/localize-prices/manual-currency-prices.md) não requer alterações na IU se você exibir o `total`. ```html
``` ```javascript const clientSecret = fetch('/create-checkout-session', {method: 'POST'}) .then((response) => response.json()) .then((json) => json.client_secret); const checkout = stripe.initCheckoutElementsSdk({clientSecret}); const loadActionsResult = await checkout.loadActions(); if (loadActionsResult.type === 'success') { const session = loadActionsResult.actions.getSession(); const checkoutContainer = document.getElementById('checkout-container'); checkoutContainer.append(JSON.stringify(session.lineItems, null, 2)); checkoutContainer.append(document.createElement('br')); checkoutContainer.append(`Total: ${session.total.total.amount}`); } ``` #### React Envolva seu aplicativo com o componente [CheckoutElementsProvider](https://docs.stripe.com/js/react_stripe_js/checkout/checkout_provider), passando `clientSecret` e a instância `stripe`. ```jsx import React from 'react'; import {CheckoutElementsProvider} from '@stripe/react-stripe-js/checkout'; import CheckoutForm from './CheckoutForm'; const clientSecret = fetch('/create-checkout-session', {method: 'POST'}) .then((response) => response.json()) .then((json) => json.client_secret); const App = () => { return ( ); }; export default App; ``` Acesse o objeto [Checkout](https://docs.stripe.com/js/custom_checkout) no componente do seu formulário de checkout usando o hook `useCheckoutElements()`. O objeto `Checkout` contém dados do Checkout Session e métodos para atualizá-lo. Leia o `total` e `lineItems` do objeto do `Checkout` e exibi-lo na sua IU. Isso permite que você ative recursos com mudanças mínimas no código. Por exemplo, somando [preços de moeda manualmente](https://docs.stripe.com/payments/custom/localize-prices/manual-currency-prices.md) não requer alterações na IU se você exibir o `total`. ```jsx import React from 'react'; import {useCheckoutElements} from '@stripe/react-stripe-js/checkout'; const CheckoutForm = () => {const checkoutState = useCheckoutElements(); if (checkoutState.type === 'loading') { return (
Loading...
); } if (checkoutState.type === 'error') { return (
Error: {checkoutState.error.message}
); } return (
{JSON.stringify(checkoutState.checkout.lineItems, null, 2)} {/* A formatted total amount */} Total: {checkoutState.checkout.total.total.amount}
); }; ``` ## Coletar e-mail do cliente [Lado do cliente] #### HTML + JS Ao concluir uma sessão do Checkout, é necessário fornecer um e-mail válido do cliente. Use o [Contact Details Element](https://docs.stripe.com/js/custom_checkout/create_contact_details_element) para coletar o endereço de e-mail do seu cliente. Ele cuida da coleta e da validação de e-mails para você, e ajuda os clientes a fazer login no Link. Ou, você pode: - Informe o [customer_email](https://docs.stripe.com/api/checkout/sessions/create.md#create_checkout_session-customer_email), [customer_account](https://docs.stripe.com/api/checkout/sessions/create.md#create_checkout_session-customer_account) (para clientes representados como objetos de `Conta` configurados pelo cliente) ou [cliente](https://docs.stripe.com/api/checkout/sessions/create.md#create_checkout_session-customer) (para clientes representados como objetos de `Cliente`) ao criar a Sessão de Checkout. A Stripe valida os e-mails fornecidos dessa forma. - Isso preenche a sessão com um e-mail que os clientes não podem editar na página de checkout. Se você quiser preencher com um e-mail editável, use [defaultValues.email](https://docs.stripe.com/js/custom_checkout/init#custom_checkout_init-options-defaultValues-email) ao inicializar o checkout. - Informe um e-mail que você já validou em [updateEmail](https://docs.stripe.com/js/custom_checkout/update_email) ou [checkout.confirm](https://docs.stripe.com/js/custom_checkout/confirm). ```html
``` ```javascript const contactDetailsElement = checkout.createContactDetailsElement(); contactDetailsElement.mount("#contact-details-element"); ``` #### React Ao concluir uma sessão do Checkout, é necessário fornecer um e-mail válido do cliente. Use o [ContactDetailsElement](https://docs.stripe.com/js/react_stripe_js/checkout/contact_details_element) para coletar o endereço de e-mail do seu cliente. Ele cuida da coleta e da validação de e-mails para você, e ajuda os clientes a fazer login no Link. Ou, você pode: - Informe o [customer_email](https://docs.stripe.com/api/checkout/sessions/create.md#create_checkout_session-customer_email), [customer_account](https://docs.stripe.com/api/checkout/sessions/create.md#create_checkout_session-customer_account) (para clientes representados como objetos de `Conta` configurados pelo cliente) ou [cliente](https://docs.stripe.com/api/checkout/sessions/create.md#create_checkout_session-customer) (para clientes representados como objetos de `Cliente`) ao criar a Sessão de Checkout. A Stripe valida os e-mails fornecidos dessa forma. - Isso preenche a sessão com um e-mail que os clientes não podem editar na página de checkout. Se você quiser preencher com um e-mail editável, use [defaultValues.email](https://docs.stripe.com/js/custom_checkout/init#custom_checkout_init-options-defaultValues-email) ao inicializar o checkout. - Informe um e-mail que você já validou em [updateEmail](https://docs.stripe.com/js/react_stripe_js/checkout/update_email) ou [confirm](https://docs.stripe.com/js/react_stripe_js/checkout/confirm). ```jsx import {ContactDetailsElement} from '@stripe/react-stripe-js/checkout'; // Inside your CheckoutForm component: ``` ## Coletar dados de pagamento [Lado do cliente] Colete dados de pagamento no cliente com o [Payment Element](https://docs.stripe.com/payments/payment-element.md). O Payment Element é um componente de IU que simplifica a coleta de dados de pagamento para diversas formas de pagamento. O Payment Element contém um iframe que envia dados de pagamento com segurança à Stripe por uma conexão HTTPS. Evite colocar o Payment Element dentro de outro iframe porque algumas formas de pagamento exigem o redirecionamento para outra página para confirmação do pagamento. Se você optar por usar um iframe e quiser aceitar Apple Pay ou Google Pay, o iframe deve ter o atributo [permitir](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/iframe#attr-allowpaymentrequest) definido como igual a `"pagamento *"`. O endereço da página de Checkout deve começar com `https://` rather em vez de `http://` for para que sua integração funcione corretamente. Você pode testar sua integração sem usar HTTPS, mas lembre-se de [habilitá-lo](https://docs.stripe.com/security/guide.md#tls) quando estiver pronto para aceitar pagamentos em tempo real. #### HTML + JS Primeiro, crie um elemento DOM de contêiner para montar o [Payment Element](https://docs.stripe.com/payments/payment-element.md). Em seguida, crie uma instância do `Payment Element` usando [checkout.createPaymentElement](https://docs.stripe.com/js/custom_checkout/create_payment_element) e monte-a chamando [element.mount](https://docs.stripe.com/js/element/mount), fornecendo um seletor CSS ou o elemento DOM do contêiner. ```html
``` ```javascript const paymentElement = checkout.createPaymentElement(); paymentElement.mount('#payment-element'); ``` Veja as opções disponíveis na documentação da [Stripe.js](https://docs.stripe.com/js/custom_checkout/create_payment_element#custom_checkout_create_payment_element-options). Você pode [personalizar a aparência](https://docs.stripe.com/payments/checkout/customization/appearance.md) de todos os Elements passando [elementsOptions.appearance](https://docs.stripe.com/js/custom_checkout/init#custom_checkout_init-options-elementsOptions-appearance) ao inicializar o Checkout no frontend. #### React Monte o componente [Payment Element](https://docs.stripe.com/payments/payment-element.md) dentro do [CheckoutElementsProvider](https://docs.stripe.com/js/react_stripe_js/checkout/checkout_provider). ```jsx import React from 'react';import {PaymentElement, useCheckoutElements} from '@stripe/react-stripe-js/checkout'; const CheckoutForm = () => { const checkoutState = useCheckoutElements(); if (checkoutState.type === 'loading') { return (
Loading...
); } if (checkoutState.type === 'error') { return (
Error: {checkoutState.error.message}
); } return (
{JSON.stringify(checkoutState.checkout.lineItems, null, 2)} {/* A formatted total amount */} Total: {checkoutState.checkout.total.total.amount} ); }; export default CheckoutForm; ``` Veja as opções disponíveis na documentação da [Stripe.js](https://docs.stripe.com/js/custom_checkout/create_payment_element#custom_checkout_create_payment_element-options). Você pode [personalizar a aparência](https://docs.stripe.com/payments/checkout/customization/appearance.md) de todos os Elements passando [elementsOptions.appearance](https://docs.stripe.com/js/react_stripe_js/checkout/checkout_provider#react_checkout_provider-options-elementsOptions-appearance) para o [CheckoutElementsProvider](https://docs.stripe.com/js/react_stripe_js/checkout/checkout_provider). ## Envie o pagamento [Lado do cliente] #### HTML + JS Renderize um botão **Pagar** que chame a [confirmação](https://docs.stripe.com/js/custom_checkout/confirm) da instância `Checkout` para enviar o pagamento. ```html
``` ```js const checkout = stripe.initCheckoutElementsSdk({clientSecret}); checkout.on('change', (session) => { document.getElementById('pay-button').disabled = !session.canConfirm; }); const loadActionsResult = await checkout.loadActions(); if (loadActionsResult.type === 'success') { const {actions} = loadActionsResult; const button = document.getElementById('pay-button'); const errors = document.getElementById('confirm-errors'); button.addEventListener('click', () => { // Clear any validation errors errors.textContent = ''; actions.confirm().then((result) => { if (result.type === 'error') { errors.textContent = result.error.message; } }); }); } ``` #### React Renderize um botão **Pay** que chama [confirm](https://docs.stripe.com/js/custom_checkout/confirm) de [useCheckoutElements](https://docs.stripe.com/js/react_stripe_js/checkout/use_checkout_elements) para enviar o pagamento. ```jsx import React from 'react'; import {useCheckoutElements} from '@stripe/react-stripe-js/checkout'; const PayButton = () => { const checkoutState = useCheckoutElements(); const [loading, setLoading] = React.useState(false); const [error, setError] = React.useState(null); if (checkoutState.type !== "success") { return null; } const handleClick = () => { setLoading(true);checkoutState.checkout.confirm().then((result) => { if (result.type === 'error') { setError(result.error) } setLoading(false); }) }; return (
{error &&
{error.message}
}
) }; export default PayButton; ``` ## Teste a integração 1. Acesse a página de checkout. 2. Preencha os dados de pagamento com uma forma de pagamento da tabela a seguir. Para pagamentos com cartão: - Informe uma data futura qualquer como validade do cartão. - Informe qualquer número de 3 dígitos como CVC. - Informe qualquer código postal de cobrança. 3. Envie o pagamento para a Stripe. 4. Acesse o Dashboard e procure o pagamento na [página Transações](https://dashboard.stripe.com/test/payments?status%5B0%5D=successful). Se o seu pagamento for bem-sucedido, ele aparecerá na lista. 5. Clique no pagamento para ver mais detalhes, como dados de cobrança e a lista de itens comprados. Você pode usar essas informações para [executar o pedido](https://docs.stripe.com/checkout/fulfillment.md). #### Cartões | Número do cartão | Cenário | Como testar | | ------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------- | | 4242424242424242 | O pagamento com cartão é bem-sucedido e não precisa de autenticação. | Preencha o formulário do cartão de crédito usando o número do cartão de crédito com qualquer validade, CVC e código postal. | | 4000002500003155 | O pagamento com cartã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 do cartão de crédito com qualquer validade, CVC e código postal. | | 4000000000009995 | O cartão é recusado com um código de recusa como `insufficient_funds`. | Preencha o formulário do cartão de crédito usando o número do cartão de crédito com qualquer validade, CVC e código postal. | | 6205500000000000004 | O cartão UnionPay tem um comprimento variável de 13 a 19 dígitos. | Preencha o formulário do cartão de crédito usando o número do cartão de crédito com qualquer validade, CVC e código postal. | #### Carteiras | Forma de pagamento | Cenário | Como testar | | ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Alipay | O cliente paga com uma forma de pagamento baseada em redirecionamento e [notificação imediata](https://docs.stripe.com/payments/payment-methods.md#payment-notification). | Escolha qualquer forma de pagamento baseada em redirecionamento, preencha os dados obrigatórios e confirme o pagamento. Em seguida, clique em **Concluir o pagamento de teste** na página de redirecionamento. | #### Débito bancário autenticado | Forma de pagamento | Cenário | Como testar | | ------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | 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` e BSB `000000`. Inicialmente, o status do PaymentIntent muda para `processing` e, 3 minutos depois, para `succeeded`. | | 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 da conta `111111113` e BSB `000000`. | | Bancontact, EPS, iDEAL, e Przelewy24 | Seu cliente não faz a autenticação na página de redirecionamento de uma forma de pagamento baseada em redirecionamento e notificação imediata. | Escolha qualquer forma de pagamento baseada em redirecionamento, preencha os dados obrigatórios e confirme o pagamento. Em seguida, clique em **Falhar pagamento de teste** na página de redirecionamento. | | Pay by Bank | O cliente paga com uma forma de pagamento baseada em redirecionamento e [notificação posterior](https://docs.stripe.com/payments/payment-methods.md#payment-notification). | Escolha a forma de pagamento, preencha os dados obrigatórios e confirme o pagamento. Em seguida, clique em **Concluir o pagamento de teste** na página de redirecionamento. | | Pay by Bank | Seu cliente não faz a autenticação na página de redirecionamento de uma forma de pagamento baseada em redirecionamento e notificação posterior. | Escolha a forma de pagamento, preencha os dados obrigatórios e confirme o pagamento. Em seguida, clique em **Falhar o pagamento de teste** na página de redirecionamento. | | BLIK | Os pagamentos BLIK falham de várias formas: falhas imediatas (por exemplo, o código está vencido ou inválido), erros atrasados (o banco recusa) ou limites de tempo (o cliente não respondeu a tempo). | Use padrões de e-mail para [simular as diferentes falhas.](https://docs.stripe.com/payments/blik/accept-a-payment.md#simulate-failures) | #### 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 do PaymentIntent muda para processando e, três minutos depois, para bem-sucedido. | | Débito automático SEPA | O status da intenção de pagamento do cliente muda de `processing` para `requires_payment_method`. | Preencha o formulário usando o número de conta `AT861904300235473202`. | #### Boletos | Forma de pagamento | Cenário | Como testar | | ------------------ | ------------------------------------------------ | ---------------------------------------------------------------------------------------------- | | Boleto, OXXO | Seu cliente paga com um boleto ou uma guia OXXO. | Selecione boleto ou OXXO como forma de pagamento e envie o pagamento. Feche o diálogo exibido. | Consulte [Testes](https://docs.stripe.com/testing.md) para obter mais informações sobre como testar sua integração. ## Optional: Criar produtos e preços Antes de criar uma Sessão do Checkout, você pode criar *Produtos* (Products represent what your business sells—whether that's a good or a service) e *Preços* (Prices define how much and how often to charge for products. This includes how much the product costs, what currency to use, and the interval if the price is for subscriptions) antecipadamente. Use produtos para representar diferentes bens físicos ou níveis de serviço, e *Preços* (Prices define how much and how often to charge for products. This includes how much the product costs, what currency to use, and the interval if the price is for subscriptions) para representar o preço de cada produto. Você também pode [configurar sua Checkout Session](https://docs.stripe.com/payments/checkout/pay-what-you-want.md) para aceitar gorjetas e doações ou vender produtos e serviços com preço definido pelo cliente. Por exemplo, você pode criar uma camiseta como produto com um preço de 20 USD. Isso permite que você atualize e adicione preços sem precisar alterar os detalhes dos produtos correspondentes. Você pode criar produtos e preços com o Stripe Dashboard ou a API. Saiba mais sobre [como funcionam produtos e preços](https://docs.stripe.com/products-prices/how-products-and-prices-work.md). #### API A API precisa apenas de um `name` para criar um [produto](https://docs.stripe.com/api/products.md). O Checkout exibe os atributos `name`, `description` e `images` informados para o produto. ```curl curl https://api.stripe.com/v1/products \ -u "<>:" \ -d name=T-shirt ``` Depois crie um [preço](https://docs.stripe.com/api/prices.md) para definir quanto cobrar pelo produto. Isso inclui quanto custa o produto e qual moeda usar. ```curl curl https://api.stripe.com/v1/prices \ -u "<>:" \ -d "product={{PRODUCT_ID}}" \ -d unit_amount=2000 \ -d currency=usd ``` #### Dashboard > Copie os produtos criados em uma área restrita para o modo de produção para que você não precise recriá-los. Na visualização de detalhes do Produto no Dashboard, clique em **Copiar para o modo de produção** no canto superior direito. Você pode copiar o mesmo produto da área restrita para o modo de produção mais de uma vez. Cada cópia cria um produto em produção separado, e as atualizações subsequentes feitas no produto da área restrita não são refletidas nas cópias de produção existentes. Para saber se você está em uma área restrita, clique em **Áreas restritas** no seletor de contas do Dashboard. Em seguida, defina os itens que deseja vender. Para criar um novo produto e preço: - Acesse a seção [Produtos](https://dashboard.stripe.com/test/products) no Dashboard. - Clique em **Adicionar produto**. - Selecione **Uma vez** ao definir o preço. O Checkout exibe o nome, a descrição e as imagens fornecidas para o produto. Cada preço que você cria tem um ID. Quando você criar uma Checkout Session, faça referência ao ID e à quantidade do preço. Se estiver vendendo em várias moedas, crie seu Price *multimoedas*. O Checkout automaticamente [determina a moeda local do cliente](https://docs.stripe.com/payments/checkout/localize-prices/manual-currency-prices.md) e apresenta essa moeda se o Price aceitar. ```curl curl https://api.stripe.com/v1/checkout/sessions \ -u "<>:" \ -d ui_mode=elements \ -d mode=payment \ -d "line_items[0][price]={{PRICE_ID}}" \ -d "line_items[0][quantity]=1" \ --data-urlencode "return_url=https://example.com/return?session_id={CHECKOUT_SESSION_ID}" ``` ## Optional: Preencher dados do cliente [Lado do servidor] Se você já coletou o e-mail do cliente e quer preenchê-lo antecipadamente na sessão de checkout, passe [customer_email](https://docs.stripe.com/api/checkout/sessions/create.md#create_checkout_session-customer_email) ao criar uma sessão de checkout. ```curl curl https://api.stripe.com/v1/checkout/sessions \ -u "<>:" \ --data-urlencode "customer_email=customer@example.com" \ -d ui_mode=elements \ -d mode=payment \ -d "line_items[0][price]={{PRICE_ID}}" \ -d "line_items[0][quantity]=1" \ --data-urlencode "return_url=https://example.com/return?session_id={CHECKOUT_SESSION_ID}" ``` ## Optional: Salvar dados da forma de pagamento Saiba como [aceitar um pagamento e salvar os dados de pagamento](https://docs.stripe.com/payments/save-during-payment.md) do seu cliente para futuras compras. ## Optional: Escutar mudanças na sessão do Checkout ### Escutar mudanças na sessão do Checkout Você pode escutar mudanças na [sessão do Checkout](https://docs.stripe.com/api/checkout/sessions.md) adicionando um ouvinte no evento `change` com [checkout.on](https://docs.stripe.com/js/custom_checkout/change_event). #### HTML + JS ```javascript checkout = stripe.initCheckoutElementsSdk({ clientSecret: promise, elementsOptions: { appearance }, }); checkout.on('change', (session) => { // Handle changes to the checkout session }); ``` #### React ```jsx import React from 'react'; import { useCheckoutElements } from '@stripe/react-stripe-js/checkout'; const CheckoutForm = () => { const checkoutState = useCheckoutElements(); if (checkoutState.type === 'success') { checkoutState.checkout.on('change', (session) => { // Handle changes to the checkout session }); } }; ``` ## Optional: Coletar endereços de cobrança e envio ## Coletar um endereço de cobrança Por padrão, uma sessão do Checkout coleta os dados mínimos de cobrança necessários para pagamento por meio do Payment Element. ### Usar o Billing Address Element Você pode coletar endereços de cobrança completos usando o Billing Address Element. Primeiro, passe [billing_address_collection=required](https://docs.stripe.com/api/checkout/sessions/create.md#create_checkout_session-billing_address_collection) ao criar a sessão do Checkout. #### HTML + JS Crie um elemento DOM de contêiner para montar o Billing Address Element. Em seguida, crie uma instância do Billing Address Element usando [checkout.createBillingAddressElement](https://docs.stripe.com/js/custom_checkout/create_billing_address_element) e monte-a chamando [element.mount](https://docs.stripe.com/js/element/mount), fornecendo um seletor CSS ou o elemento DOM do contêiner. ```html
``` ```javascript const billingAddressElement = checkout.createBillingAddressElement(); billingAddressElement.mount('#billing-address'); ``` O Billing Address Element aceita as seguintes opções: - [contacts](https://docs.stripe.com/js/custom_checkout/create_billing_address_element#custom_checkout_create_billing_address_element-options-contacts) - [display](https://docs.stripe.com/js/custom_checkout/create_billing_address_element#custom_checkout_create_billing_address_element-options-display) #### React Monte o componente `BillingAddressElement` dentro do `CheckoutElementsProvider`. ```jsx import React from 'react'; import {BillingAddressElement} from '@stripe/react-stripe-js/checkout'; const CheckoutForm = () => { return (
) }; ``` O Billing Address Element aceita os seguintes elementos: - [contacts](https://docs.stripe.com/js/custom_checkout/create_billing_address_element#custom_checkout_create_billing_address_element-options-contacts) - [display](https://docs.stripe.com/js/custom_checkout/create_billing_address_element#custom_checkout_create_billing_address_element-options-display) ### Usar um formulário personalizado Você pode criar seu próprio formulário para coletar endereços de cobrança. - Se sua página de checkout tiver uma etapa distinta de coleta de endereço antes da confirmação, chame [updateBillingAddress](https://docs.stripe.com/js/react_stripe_js/checkout/update_billing_address) quando seu cliente enviar o endereço. - Caso contrário, você pode enviar o endereço quando o cliente clicar no botão “Pagar”, passando [billingAddress](https://docs.stripe.com/js/custom_checkout/confirm#custom_checkout_session_confirm-options-billingAddress) para [confirm](https://docs.stripe.com/js/custom_checkout/confirm). ### Coletar endereços de cobrança parciais Para coletar endereços de cobrança parciais, como apenas o país e o código postal, passe [billing_address_collection=auto](https://docs.stripe.com/api/checkout/sessions/create.md#create_checkout_session-billing_address_collection). Ao coletar endereços de cobrança parciais, você deve [coletar endereços manualmente](https://docs.stripe.com/payments/accept-a-payment.md#collect-billing-addresses-manually). Por padrão, o Payment Element coleta automaticamente os dados mínimos de cobrança necessários para o pagamento. Para evitar a coleta dupla de dados de cobrança, passe [fields.billingDetails=never](https://docs.stripe.com/js/custom_checkout/create_payment_element#custom_checkout_create_payment_element-options-fields-billingDetails) quando criar o Payment Element. Se você pretende coletar apenas um subconjunto de dados de cobrança (como o nome do cliente), passe `never` apenas para os campos que você pretende coletar por conta própria. ## Coletar um endereço de entrega Para coletar o endereço de entrega de um cliente, passe o parâmetro [shipping_address_collection](https://docs.stripe.com/api/checkout/sessions/create.md#create_checkout_session-shipping_address_collection) ao criar a sessão do Checkout. Quando você coleta um endereço de entrega, também precisa especificar para quais países deseja efetuar entregas. Configure a propriedade [allowed_countries](https://docs.stripe.com/api/checkout/sessions/create.md#create_checkout_session-shipping_address_collection-allowed_countries) com uma matriz de [códigos de país ISO de duas letras](https://www.nationsonline.org/oneworld/country_code_list.htm). ### Como usar o Shipping Address Element Você pode coletar endereços de entrega completos com o Shipping Address Element. #### HTML + JS Crie um elemento DOM de contêiner para montar o Shipping Address Element. Em seguida, crie uma instância do Shipping Address Element usando [checkout.createShippingAddressElement](https://docs.stripe.com/js/custom_checkout/create_shipping_address_element) e monte-a chamando [element.mount](https://docs.stripe.com/js/element/mount), fornecendo um seletor CSS ou o elemento DOM do contêiner. ```html
``` ```javascript const shippingAddressElement = checkout.createShippingAddressElement(); shippingAddressElement.mount('#shipping-address'); ``` O Shipping Address Element aceita as seguintes opções: - [contacts](https://docs.stripe.com/js/custom_checkout/create_shipping_address_element#custom_checkout_create_shipping_address_element-options-contacts) - [display](https://docs.stripe.com/js/custom_checkout/create_shipping_address_element#custom_checkout_create_shipping_address_element-options-display) #### React Monte o componente `ShippingAddressElement` dentro do `CheckoutElementsProvider`. ```jsx import React from 'react'; import {ShippingAddressElement} from '@stripe/react-stripe-js/checkout'; const CheckoutForm = () => { return (
) }; ``` O Shipping Address Element aceita os seguintes elementos: - [contacts](https://docs.stripe.com/js/custom_checkout/create_shipping_address_element#custom_checkout_create_shipping_address_element-options-contacts) - [display](https://docs.stripe.com/js/custom_checkout/create_shipping_address_element#custom_checkout_create_shipping_address_element-options-display) ### Escutar mudanças na sessão do Checkout Você pode escutar alterações na [sessão do Checkout](https://docs.stripe.com/api/checkout/sessions.md) adicionando um ouvinte de eventos para gerenciar alterações relacionadas ao endereço. #### HTML + JS Use o [objeto Session](https://docs.stripe.com/js/custom_checkout/session_object) para processar o valor do envio no formulário de checkout. ```html

Totals

``` ```javascript const checkout = stripe.initCheckoutElementsSdk({clientSecret}); const subtotal = document.getElementById('subtotal'); const shipping = document.getElementById('shipping'); const total = document.getElementById('total'); checkout.on('change', (session) => { subtotal.textContent = `Subtotal: ${session.total.subtotal.amount}`; shipping.textContent = `Shipping: ${session.total.shippingRate.amount}`; total.textContent = `Total: ${session.total.total.amount}`; }); ``` #### React Use [useCheckoutElements](https://docs.stripe.com/js/react_stripe_js/checkout/use_checkout_elements) para renderizar o custo de envio no seu formulário de checkout. ```jsx import React from 'react'; import {useCheckoutElements, ShippingAddressElement} from '@stripe/react-stripe-js/checkout'; const CheckoutForm = () => { const checkoutState = useCheckoutElements(); if (checkoutState.type === 'error') { return (
Error: {checkoutState.error.message}
); } return (

Checkout Summary

{checkoutState.type === 'success' && ( <> 
              {JSON.stringify(checkoutState.checkout.lineItems, null, 2)}

Totals

              Subtotal: {checkoutState.checkout.total.subtotal.amount}
              Shipping: {checkoutState.checkout.total.shippingRate.amount}
              Total: {checkoutState.checkout.total.total.amount}
)}
) }; ``` ### Sincronizar endereços de faturamento e entrega Ao usar o Billing Address Element e Shipping Address Element, você pode exibir uma caixa de seleção que permite aos clientes sincronizar os endereços de cobrança e entrega. #### HTML + JS Passe a opção [syncAddressCheckbox](https://docs.stripe.com/js/custom_checkout/init#custom_checkout_init-options-elementsOptions-syncAddressCheckbox) em `elementsOptions` ao inicializar o Checkout para configurar qual Address Element exibe a caixa de seleção. ```javascript const checkout = stripe.initCheckoutElementsSdk({ clientSecret, elementsOptions: { syncAddressCheckbox: 'shipping', }, }); ``` #### React Passe a opção [syncAddressCheckbox](https://docs.stripe.com/js/react_stripe_js/checkout/checkout_provider#react_checkout_provider-options-elementsOptions-syncAddressCheckbox) em `elementsOptions` para o `CheckoutElementsProvider` para configurar qual Address Element mostra a caixa de seleção. ```jsx promise, elementsOptions: { syncAddressCheckbox: 'shipping', }, }} > ``` Defina o valor como `'billing'` ou `'shipping'` para escolher qual Address Element exibe a caixa de seleção. Defina como `'none'` para ocultar a caixa de seleção, ou deixe em branco para usar o valor padrão (`'billing'`). ### Usar um formulário personalizado Você pode criar seu próprio formulário para coletar endereços de entrega. - Se sua página de checkout tiver uma etapa distinta de coleta de endereço antes da confirmação, chame [updateShippingAddress](https://docs.stripe.com/js/react_stripe_js/checkout/update_shipping_address) quando seu cliente enviar o endereço. - Caso contrário, você pode enviar o endereço quando o cliente clicar no botão “Pagar”, passando [shippingAddress](https://docs.stripe.com/js/custom_checkout/confirm#custom_checkout_session_confirm-options-shippingAddress) para [confirm](https://docs.stripe.com/js/custom_checkout/confirm). ## Optional: Separar autorização e captura [Lado do servidor] A Stripe é compatível com pagamento com cartão em dois passos, então você pode primeiro autorizar um cartão e depois captura os fundos posteriormente. Quando a Stripe autoriza um pagamento, o cartão emissor garante os fundos e bloqueia o valor do pagamento no cartão do cliente. Em seguida, você tem um certo tempo para capturar os fundos,[dependendo do cartão](https://docs.stripe.com/payments/place-a-hold-on-a-payment-method.md#auth-capture-limitations)). Se você não captura o pagamento antes do vencimento da autorização, o pagamento é cancelado e o emissor libera os fundos retidos. Separar a autorização da captura é útil para quem precisa realizar outros procedimentos entre a confirmação de que o cliente pode pagar e a cobrança do pagamento. Por exemplo, se você estiver vendendo itens com estoque limitado, pode ser necessário confirmar que o item comprado pelo cliente usando o Checkout ainda está disponível antes de capturar o pagamento e concluir a compra. Faça isso usando o seguinte fluxo de trabalho: 1. Confirme se a Stripe autorizou a forma de pagamento do cliente. 2. Consulte seu sistema de gestão de inventário para saber se o item ainda está disponível. 3. Atualize seu sistema de gestão de inventário para indicar que o cliente comprou o item. 4. Capture o pagamento do cliente. 5. Informe ao cliente se a compra foi finalizada em sua página de confirmação. Para indicar que você quer separar a autorização da captura, defina [payment_intent_data.capture_method](https://docs.stripe.com/api/checkout/sessions/create.md#create_checkout_session-payment_intent_data-capture_method) como `manual` quando criar a sessão do Checkout. Isso instrui a Stripe a autorizar somente o valor no cartão do cliente. ```curl curl https://api.stripe.com/v1/checkout/sessions \ -u "<>:" \ -d "line_items[0][price]={{PRICE_ID}}" \ -d "line_items[0][quantity]=1" \ -d mode=payment \ -d "payment_intent_data[capture_method]=manual" \ -d return_url={{RETURN_URL}} \ -d ui_mode=elements ``` Para capturar um pagamento pendente, você pode usar o [Dashboard](https://dashboard.stripe.com/test/payments?status%5B%5D=uncaptured) ou o endpoint [capture](https://docs.stripe.com/api/payment_intents/capture.md). Para capturar automaticamente os pagamentos, é preciso ter acesso ao PaymentIntent criado durante a sessão do Checkout, que você pode obter pelo objeto [Session](https://docs.stripe.com/api/payment_intents/capture.md). ## Optional: Gerenciamento de contas de clientes [Sem código] Permita que seus clientes [gerenciem](https://docs.stripe.com/customer-management.md) as próprias contas, compartilhando um link para o seu *portal do cliente* (The customer portal is a secure, Stripe-hosted page that lets your customers manage their subscriptions and billing details). O portal do cliente permite que os clientes façam login com o próprio e-mail para gerenciar assinaturas, atualizar formas de pagamento e muito mais. ## Optional: Execução de pedidos Saiba como [receber uma notificação automaticamente](https://docs.stripe.com/checkout/fulfillment.md?payment-ui=embedded-components) quando um cliente paga. ## See also - [Adicione descontos para pagamentos únicos](https://docs.stripe.com/payments/advanced/discounts.md) - [Recolha impostos](https://docs.stripe.com/tax/checkout/elements.md) - [Habilite quantidades ajustáveis de itens de linha](https://docs.stripe.com/payments/advanced/adjustable-quantity.md) - [Adicionar botões de um clique](https://docs.stripe.com/elements/express-checkout-element/accept-a-payment.md?payment-ui=embedded-components) - [Projeto de exemplo no GitHub](https://github.com/stripe-samples/accept-a-payment/tree/main/elements-with-checkout-sessions)