Pular para o conteúdo
Criar conta ou Entrar
O logotipo da documentação da Stripe
/
Criar contaLogin
Visão geralAtualize sua integração
Pagamentos online
Visão geralEncontre seu caso de usoUsar o Managed Payments
Pagamentos presenciais
Formas de pagamento
Cenários de pagamento
Muito mais que pagamentos

Aceitar um pagamento

Aceitar pagamentos online com segurança

Crie um formulário de pagamento ou use uma página de checkout pré-integrada para começar a aceitar pagamentos online.

Crie uma página de checkout no seu site usando o Stripe Elements e a Checkout Sessions, uma integração que gerencia impostos, descontos, tarifas de envio e muito mais.

Localização do cliente
Tamanho
Tema
Layout
Esta demonstração só exibe o Google Pay ou Apple Pay se você tiver um cartão ativo com qualquer uma das carteiras.

Configure o servidor
Lado do servidor

Antes de começar, você precisa se cadastrar para uma conta Stripe.

Use as bibliotecas Stripe oficiais para acessar o API do seu aplicativo.

Command Line
Node.js
Ruby
PHP
Python
Go
.NET
Java
No results
npm install stripe@18.0.0 --save

Configure o SDK para usar pelo menos a versão de API 2025-03-31.basil.

TypeScript
Node.js
Ruby
PHP
Python
Go
.NET
Java
No results
// Set your secret key. Remember to switch to your live secret key in production.
// See your keys here: https://dashboard.stripe.com/apikeys
import Stripe from 'stripe';
const stripe = new Stripe(
'sk_test_BQokikJOvBiI2HlWgH4olfQ2'
, {
  apiVersion: '2025-03-31.basil' as any,
});

Criar uma sessão do Checkout
Lado do servidor

Adicione um endpoint ao seu servidor que cria uma sessão do Checkout e retorna seu segredo do cliente para o frontend. Uma sessão do Checkout representa a sessão do seu cliente enquanto ele paga por compras ou assinaturas avulsas. As sessões do Checkout expiram 24 horas após a criação.

server.ts
TypeScript
Node.js
Ruby
PHP
Python
Go
.NET
Java
No results
import express, {Express} from 'express';

const app: Express = express();

app.post('/create-checkout-session', async (req: Express.Request, res: Express.Response) => {
  const session = await stripe.checkout.sessions.create({
    line_items: [
      {
        price_data: {
          currency: 'usd',
          product_data: {
            name: 'T-shirt',
          },
          unit_amount: 2000,
        },
        quantity: 1,
      },
    ],
    mode: 'payment',
    ui_mode: 'custom',
    // The URL of your payment completion page
    return_url: 'https://example.com/return?session_id={CHECKOUT_SESSION_ID}'
  });

  res.json({checkoutSessionClientSecret: session.client_secret});
});

app.listen(3000, () => {
  console.log('Running on port 3000');
});

Configurar o frontend
Lado do cliente

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.

Ensure you’re on the latest Stripe.js version by including the following script tag <script src=“https://js.stripe.com/clover/stripe.js”></script>. Learn more about Stripe.js versioning.

checkout.html
<head>
  <title>Checkout</title>
  <script src="https://js.stripe.com/clover/stripe.js"></script>
</head>

Observação

A Stripe fornece um pacote npm que você pode usar para carregar o Stripe.js como um módulo. Veja o projeto no GitHub. A versão 7.0.0 ou posterior é necessária.

Inicialize o Stripe.js.

checkout.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(
  
'pk_test_TYooMQauvdEDq54NiTphI7jx'
,
);

Inicializar o Checkout
Lado do cliente

Crie um clientSecret como uma promessa (promise) que retorna o segredo do cliente ou defina-o diretamente como o segredo. Em seguida, chame initCheckout, passando o clientSecret. O initCheckout devolve uma promessa que se resolve em uma instância de Checkout.

O objeto checkout representa a estrutura da sua página de checkout e contém os dados da sessão e métodos para atualizações em tempo real.

O objeto retornado por actions.getSession() contém suas informações de preços. Recomendamos a leitura e exibição dototal elineItems da sessão em seu IU.

Isso permite que você ative novos recursos com alterações mínimas no código. Por exemplo, adicionar preços de moedas manualmente não requer alterações na IU se você exibir o total .

checkout.js
const clientSecret = fetch('/create-checkout-session', {method: 'POST'})
  .then((response) => response.json())
  .then((json) => json.checkoutSessionClientSecret);
const checkout = stripe.initCheckout({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}`);
}
index.html
<div id="checkout-container"></div>

Coletar e-mail do cliente
Lado do cliente

Crie uma entrada de e-mail para coletar o endereço de e-mail do cliente. Chame updateEmail quando o cliente terminar a entrada para validar e salvar o endereço de e-mail.

Dependendo do design do seu formulário de checkout, você pode chamar updateEmail das seguintes maneiras:

  • Diretamente antes de enviar o pagamento. Você também pode chamar updateEmail para antecipar a validação, como no desfoque de entrada.
  • Antes de passar para a próxima etapa, como clicar em um botão Salvar, se o formulário incluir várias etapas.
index.html
<input type="text" id="email" />
<div id="email-errors"></div>
checkout.js
const checkout = stripe.initCheckout({clientSecret});
const loadActionsResult = await checkout.loadActions();

if (loadActionsResult.type === 'success') {
  const {actions} = loadActionsResult;
  const emailInput = document.getElementById('email');
  const emailErrors = document.getElementById('email-errors');

  emailInput.addEventListener('input', () => {
    // Clear any validation errors
    emailErrors.textContent = '';
  });

  emailInput.addEventListener('blur', () => {
    const newEmail = emailInput.value;
    actions.updateEmail(newEmail).then((result) => {
      if (result.error) {
        emailErrors.textContent = result.error.message;
      }
    });
  });
}

Coletar dados de pagamento
Lado do cliente

Colete dados de pagamento no cliente com o Payment Element. O Payment Element é um componente de IU que simplifica a coleta de dados de pagamento para diversas formas de pagamento.

Primeiro, crie um elemento DOM de contêiner para montar o Payment Element. Em seguida, crie uma instância do Payment Element usando checkout.createPaymentElement e monte-a chamando element.mount, fornecendo um seletor CSS ou o elemento DOM do contêiner.

index.html
<div id="payment-element"></div>
checkout.js
const paymentElement = checkout.createPaymentElement();
paymentElement.mount('#payment-element');

Veja as opções disponíveis na documentação da Stripe.js.

Você pode personalizar a aparência de todos os Elements passando elementsOptions.appearance ao inicializar o Checkout no frontend.

Envie o pagamento
Lado do cliente

Renderize um botão Pagar que invoque confirm a partir da instância de Checkout para processar o pagamento.

index.html
<button id="pay-button">Pay</button>
<div id="confirm-errors"></div>
checkout.js
const checkout = stripe.initCheckout({clientSecret});
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;
      }
    });
  });
}

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. 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.
Número do cartãoCenárioComo testar
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.
O pagamento com cartã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.
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.
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.

Consulte Testes para obter mais informações sobre como testar sua integração.

OpcionalCriar produtos e preços

Antes de criar uma sessão do Checkout , você pode criar antecipadamente Products e Prices. Use produtos para representar diferentes produtos físicos ou níveis de serviço e Prices para representar os preços de cada produto.

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.

A API precisa apenas de um name para criar um produto. O Checkout exibe os atributos name, description e images informados para o produto.

Command Line
cURL
Stripe CLI
Ruby
Python
PHP
Java
Node.js
Go
.NET
No results
curl https://api.stripe.com/v1/products \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -d name=T-shirt

Depois crie um preço para definir quanto cobrar pelo produto. Isso inclui quanto custa o produto e qual moeda usar.

Command Line
cURL
Stripe CLI
Ruby
Python
PHP
Java
Node.js
Go
.NET
No results
curl https://api.stripe.com/v1/prices \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -d product=
"{{PRODUCT_ID}}"
 \
  -d unit_amount=2000 \
  -d currency=usd

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 e apresenta essa moeda se o Price aceitar.

Command Line
cURL
Stripe CLI
Ruby
Python
PHP
Java
Node.js
Go
.NET
No results
curl https://api.stripe.com/v1/checkout/sessions \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -d ui_mode=custom \
  -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}"

OpcionalPreencher 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 ao criar uma sessão de checkout.

Command Line
cURL
Stripe CLI
Ruby
Python
PHP
Java
Node.js
Go
.NET
No results
curl https://api.stripe.com/v1/checkout/sessions \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  --data-urlencode customer_email="customer@example.com" \
  -d ui_mode=custom \
  -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}"

OpcionalSalvar dados da forma de pagamento

Saiba como aceitar um pagamento e salvar os dados de pagamento do cliente para compras futuras.

OpcionalEscutar 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 adicionando um ouvinte no evento change com checkout.on.

checkout.js
checkout = stripe.initCheckout({
  clientSecret: promise,
  elementsOptions: { appearance },
});

checkout.on('change', (session) => {
  // Handle changes to the checkout session
});

OpcionalColetar 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 ao criar a sessão do Checkout.

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 e monte-a chamando element.mount, fornecendo um seletor CSS ou o elemento DOM do contêiner.

index.html
<div id="billing-address"></div>
checkout.js
const billingAddressElement = checkout.createBillingAddressElement();
billingAddressElement.mount('#billing-address');

O Billing Address Element aceita as seguintes opções:

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 de coleta de endereços diferente antes da confirmação, chame updateBillingAddress quando o cliente enviar o endereço.
  • Caso contrário, você pode enviar o endereço quando o cliente clicar no botão “Pagar”, passando billingAddress para 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.

Ao coletar endereços de cobrança parciais, você deve coletar endereços manualmente. 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 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 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 com uma matriz de códigos de país ISO de duas letras.

Como usar o Shipping Address Element

Você pode coletar endereços de entrega completos com o Shipping Address Element.

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 e monte-a chamando element.mount, fornecendo um seletor CSS ou o elemento DOM do contêiner.

index.html
<div id="shipping-address"></div>
checkout.js
const shippingAddressElement = checkout.createShippingAddressElement();
shippingAddressElement.mount('#shipping-address');

O Shipping Address Element aceita as seguintes opções:

Escutar mudanças na sessão do Checkout

Você pode escutar alterações na sessão do Checkout adicionando um ouvinte de eventos para gerenciar alterações relacionadas ao endereço.

Use o objeto Session para processar o valor do envio no formulário de checkout.

index.html
<div>
  <h3> Totals </h3>
  <div id="subtotal" ></div>
  <div id="shipping" ></div>
  <div id="total" ></div>
</div>
checkout.js
const checkout = stripe.initCheckout({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}`;
});

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 de coleta de endereço diferente antes da confirmação, chame updateShippingAddress quando o cliente enviar o endereço.
  • Caso contrário, você pode enviar o endereço quando o cliente clicar no botão “Pagar”, passando shippingAddress para confirm.

OpcionalSeparar autorização e captura
Lado do servidor

A Stripe aceita pagamentos com cartão em duas etapas. Assim, você pode autorizar o cartão e depois capturar os fundos. Quando a Stripe autoriza um pagamento, o emissor do cartão garante os fundos e faz uma retenção do valor do pagamento no cartão do cliente. Você tem um determinado tempo para capturar os fundos, dependendo do cartão. Se você não capturar o pagamento antes do vencimento da autorização, ele será cancelado e o emissor liberará 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ê tem limite de estoque, pode ser necessário confirmar se o item comprado pelo cliente usando o Checkout ainda está disponível, antes de capturar o pagamento e executar o pedido. Para isso, use este 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 como manual quando criar a sessão do Checkout. Isso instrui a Stripe a autorizar somente o valor no cartão do cliente.

Command Line
cURL
Stripe CLI
Ruby
Python
PHP
Java
Node.js
Go
.NET
No results
curl https://api.stripe.com/v1/checkout/sessions \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -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=custom

Para capturar um pagamento pendente, você pode usar o Dashboard ou o endpoint capture. Para capturar automaticamente os pagamentos, é preciso ter acesso ao PaymentIntent criado durante a sessão do Checkout, que você pode obter pelo objeto Session.

OpcionalGerenciamento de contas de clientes
Sem código

Permita que seus clientes gerenciem as próprias contas, compartilhando um link para o seu portal do cliente. 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.

OpcionalExecução de pedidos

Saiba como receber uma notificação automaticamente quando um cliente paga.

Veja também

Esta página foi útil?
SimNão
Code quickstart
Guias relacionados
API Elements Appearance
Mais cenários de pagamento
Como funcionam os cartões