# Pagamentos por boleto

Veja como aceitar boletos, uma forma de pagamento comum no Brasil.

# Checkout

> This is a Checkout for when payment-ui is checkout. View the full page at https://docs.stripe.com/payments/boleto/accept-a-payment?payment-ui=checkout.

> A Stripe pode apresentar automaticamente as formas de pagamento relevantes aos seus clientes avaliando moedas, restrições de formas de pagamento e outros parâmetros.
> 
> - Siga o guia [Aceitar um pagamento](https://docs.stripe.com/payments/accept-a-payment.md?payment-ui=checkout&ui=stripe-hosted) para elaborar uma integração de checkout que usa [formas de pagamento dinâmicas](https://docs.stripe.com/payments/payment-methods/dynamic-payment-methods.md).
- Se você não quiser usar o formas de pagamento dinâmico, siga as etapas abaixo para configurar manualmente as formas de pagamento em sua integração de checkout.

Boleto é uma forma de pagamento de [uso único](https://docs.stripe.com/payments/payment-methods.md#usage), que exige que o cliente [siga instruções adicionais](https://docs.stripe.com/payments/payment-methods.md#customer-actions) para finalizar o pagamento. Os *Clientes* (Customer objects represent customers of your business. They let you reuse payment methods and give you the ability to track multiple payments) pagam usando um boleto com um número gerado em caixas eletrônicos, bancos, internet banking ou agências autorizadas.

## Verificar a compatibilidade

**Localizações aceitas para empresas**: BR

**Moedas aceitas**: `brl`

**Moedas de apresentação**: `brl`

**Modo de pagamento**: Yes

**Modo de configuração**: No

**Modo de assinatura**: Yes

Uma sessão de checkout precisa satisfazer a seguinte condição para aceitar pagamentos com boleto bancário:

- Os *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) de todos os produtos incluídos no checkout precisam estar na mesma moeda. Se você tiver produtos em moedas diferentes, crie sessões do Checkout separadas para cada moeda.

## Aceitar um pagamento

> Crie uma integração para [aceitar um pagamento](https://docs.stripe.com/payments/accept-a-payment.md?integration=checkout) com o Checkout antes de usar este guia.

Isto orienta você na ativação do Boleto e mostra as diferenças entre aceitar pagamentos usando formas de pagamento dinâmicos e configurar manualmente as formas de pagamento.

### Habilitar boletos como forma de pagamento

Ao criar uma [sessão do Checkout](https://docs.stripe.com/api/checkout/sessions.md), é preciso:

1. Acrescentar `boleto` à lista de `payment_method_types`.
1. Verificar se todos os itens incluídos em `line_items` estão na moeda `brl`.

#### Página hospedada pela Stripe

```curl
curl https://api.stripe.com/v1/checkout/sessions \
  -u "<<YOUR_SECRET_KEY>>:" \
  -d "line_items[0][price_data][currency]=brl" \
  -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 \
  -d "payment_method_types[0]=card" \
  -d "payment_method_types[1]=boleto" \
  --data-urlencode "success_url=https://example.com/success"
```

#### Formulário integrado

```curl
curl https://api.stripe.com/v1/checkout/sessions \
  -u "<<YOUR_SECRET_KEY>>:" \
  -d "line_items[0][price_data][currency]=brl" \
  -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 \
  -d "payment_method_types[0]=card" \
  -d "payment_method_types[1]=boleto" \
  --data-urlencode "return_url=https://example.com/return" \
  -d ui_mode=embedded_page
```

### Outras opções da forma de pagamento

Você pode especificar um parâmetro `expires_after_days` opcional nas [opções de formas de pagamento](https://docs.stripe.com/api/checkout/sessions/create.md#create_checkout_session-payment_method_options-boleto-expires_after_days) para a sua`Sessão` que define o número de dias corridos antes que uma guia de Boleto expire. Por exemplo, se você criar uma guia de Boleto na segunda-feira e definir`expires_after_days` para 2, a guia de Boleto expira na quarta-feira às 23:59 (UTC-3), horário da América/Sao_Paulo. Se você defini-lo como 0, a guia de Boleto expira no final do dia. O parâmetro `expires_after_days` pode ser definido de 0 a 60 dias. O padrão são 3 dias. Você pode personalizar os dias de validade padrão em sua conta nas[Configurações de formas de pagamento](https://dashboard.stripe.com/settings/payment_methods).

#### Página hospedada pela Stripe

```curl
curl https://api.stripe.com/v1/checkout/sessions \
  -u "<<YOUR_SECRET_KEY>>:" \
  -d "line_items[0][price_data][currency]=brl" \
  -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 \
  -d "payment_method_options[boleto][expires_after_days]=7" \
  -d "payment_method_types[0]=card" \
  -d "payment_method_types[1]=boleto" \
  --data-urlencode "success_url=https://example.com/success"
```

#### Formulário integrado

```curl
curl https://api.stripe.com/v1/checkout/sessions \
  -u "<<YOUR_SECRET_KEY>>:" \
  -d "line_items[0][price_data][currency]=brl" \
  -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 \
  -d "payment_method_options[boleto][expires_after_days]=7" \
  -d "payment_method_types[0]=card" \
  -d "payment_method_types[1]=boleto" \
  --data-urlencode "return_url=https://example.com/return" \
  -d ui_mode=embedded_page
```

### Redirecionar para a interface de boletos da Stripe

> Ao contrário dos pagamentos com cartão, o cliente não é redirecionado para o [success_url](https://docs.stripe.com/api/checkout/sessions/object.md#checkout_session_object-success_url) nos pagamentos com boleto.

Depois de enviar corretamente o formulário do Checkout, o cliente é redirecionado para `hosted_voucher_url`. O cliente pode copiar o número do boleto ou baixá-lo em PDF nessa página.

A Stripe envia um evento [payment_intent.requires_action](https://docs.stripe.com/api/events/types.md#event_types-payment_intent.requires_action) quando um boleto é criado. Para enviar um e-mail ao cliente com o link para o boleto, pode localizar o link `hosted_voucher_url` em [payment_intent.next_action.boleto_display_details](https://docs.stripe.com/api/payment_intents/object.md#payment_intent_object-next_action-boleto_display_details-hosted_voucher_url). Saiba mais sobre como [monitorar um PaymentIntent com webhooks](https://docs.stripe.com/payments/payment-intents/verifying-status.md#webhooks).

A Stripe permite personalizar as IUs exibidas para seus clientes na página [Configurações da marca](https://dashboard.stripe.com/account/branding). As seguintes definições de marca podem ser aplicadas à guia:

- **Ícone**: a imagem de sua marca e nome fantasia da empresa
- **Cor de destaque**: usada no botão Copiar número
- **Cor da marca**: usada como cor de fundo

### Execute seu pedidos

Como o boleto é uma forma de pagamento de notificação posterior, é preciso usar um método como *webhooks* (A webhook is a real-time push notification sent to your application as a JSON payload through HTTPS requests) para monitorar o status do pagamento e gerenciar o *processamento* (Fulfillment is the process of providing the goods or services purchased by a customer, typically after payment is collected) de pedidos. Saiba [como configurar webhooks e processar pedidos](https://docs.stripe.com/checkout/fulfillment.md).

Os seguintes eventos são enviados quando há mudança no status do pagamento:

| Nome do evento                                                                                                                               | Descrição                                                                                                                                                                    | Próximas etapas                                                                      |
| -------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------ |
| [checkout.session.completed](https://docs.stripe.com/api/events/types.md#event_types-checkout.session.completed)                             | O cliente enviou o formulário do Checkout. A Stripe gerou o boleto.

  Você pode enviar o link do `hosted_voucher_url` por e-mail, para o caso de o cliente perder o boleto. | Espere que o cliente pague o boleto.                                                 |
| [checkout.session.async_payment_succeeded](https://docs.stripe.com/api/events/types.md#event_types-checkout.session.async_payment_succeeded) | O cliente pagou o boleto corretamente. O status do `PaymentIntent` muda para `succeeded`.                                                                                    | Execute o pedido de mercadorias ou serviços do cliente.                              |
| [checkout.session.async_payment_failed](https://docs.stripe.com/api/events/types.md#event_types-checkout.session.async_payment_failed)       | O boleto venceu ou o pagamento não foi concluído. O `PaymentIntent` retorna para o status de `requires_payment_method`.                                                      | Entre em contato com o cliente por e-mail e solicite a realização de um novo pedido. |

## Teste sua integração

Para testar a integração do Checkout, selecione Boleto como forma de pagamento e clique em **Pagar**.

| E-mail                                         | Descrição                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| ---------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `{any_prefix}@{any_domain}`                    | Simula um boleto pago pelo cliente depois de 3 minutos, com o webhook `payment_intent.succeeded` recebido depois de cerca de 3 minutos. Em produção, este webhook chega 1&nbsp;dia útil após o pagamento.

  Exemplo: fulaninho@exemplo.com.br                                                                                                                                                                                                                                                                                                                                                                                                          |
| `{any_prefix}succeed_immediately@{any_domain}` | Simula um boleto pago imediatamente pelo cliente, com o webhook `payment_intent.succeeded` recebido depois de alguns segundos. Em produção, este webhook chega 1&nbsp;dia útil após o pagamento.

  Exemplo: succeed_immediately@exemplo.com.br                                                                                                                                                                                                                                                                                                                                                                                                         |
| `{any_prefix}expire_immediately@{any_domain}`  | Simula um boleto que vence sem ser pago pelo cliente, com o webhook `payment_intent.payment_failed` recebido depois de alguns segundos.

  O campo `expires_at` em [next_action.boleto_display_details](https://docs.stripe.com/api/payment_intents/object.md#payment_intent_object-next_action-boleto_display_details-expires_at) está configurado para o horário atual, independente da configuração do parâmetro `expires_after_days` em [opções de forma de pagamento](https://docs.stripe.com/api/payment_intents/create.md#create_payment_intent-payment_method_options-boleto-expires_after_days).

  Exemplo: expire_immediately@exemplo.com.br |
| `{any_prefix}expire_with_delay@{any_domain}`   | Simula um boleto que vence sem ser pago pelo cliente, com o webhook `payment_intent.payment_failed` recebido depois de 3 minutos.

  O campo `expires_at` em [next_action.boleto_display_details](https://docs.stripe.com/api/payment_intents/object.md#payment_intent_object-next_action-boleto_display_details-expires_at) está configurado para 3 minutos no futuro, independente da configuração do parâmetro `expires_after_days` em [opções de forma de pagamento](https://docs.stripe.com/api/payment_intents/create.md#create_payment_intent-payment_method_options-boleto-expires_after_days).

  Exemplo: expire_with_delay@exemplo.com.br    |
| `{any_prefix}fill_never@{any_domain}`          | Simula um boleto que nunca é pago; ele expira de acordo com o campo `expires_at` em [next_action.boleto_display_details](https://docs.stripe.com/api/payment_intents/object.md#payment_intent_object-next_action-boleto_display_details-expires_at) de acordo com os parâmetros informados em [opções de forma de pagamento](https://docs.stripe.com/api/payment_intents/create.md#create_payment_intent-payment_method_options-boleto-expires_after_days). O webhook `payment_intent.payment_failed` é recebido em seguida.

  Exemplo: fill_never@exemplo.com.br                                                                                      |

| Código Fiscal                                     | Descrição                                                                                                 |
| ------------------------------------------------- | --------------------------------------------------------------------------------------------------------- |
| CPF `000.000.000-00`

  CNPJ `00.000.000/0000-00` | Em uma área restrita, defina `tax_id` como esses valores, para que eles ignorem a validação do ID fiscal. |

## Gerenciar reembolsos

Pagamentos em boleto não podem ser reembolsados. Alguns comerciantes criam um processo exclusivo para repassar o crédito diretamente aos clientes solicitantes.

## Gerenciar contestações

Não é possível contestar pagamentos por boleto.

## Optional: Enviar e-mails de instrução de pagamento

Você pode habilitar e-mails com instruções de pagamento do boleto na página [Configurações de e-mail](https://dashboard.stripe.com/settings/emails) no Dashboard. Após a habilitação, a Stripe envia e-mails com instruções de pagamento na confirmação do PaymentIntent. Os e-mails contêm o número do boleto e um link para a página do boleto hospedada na Stripe.

> Nos ambientes de teste, os e-mails com instruções só são enviados para endereços de e-mail vinculados à conta Stripe.

## See also

- [Execução do checkout](https://docs.stripe.com/checkout/fulfillment.md)
- [Personalizar o Checkout](https://docs.stripe.com/payments/checkout/customization.md)


# API Checkout Sessions

> This is a API Checkout Sessions for when payment-ui is elements and api-integration is checkout. View the full page at https://docs.stripe.com/payments/boleto/accept-a-payment?payment-ui=elements&api-integration=checkout.

Para determinar qual API atende melhor às necessidades do seu negócio, consulte o [guia de comparação](https://docs.stripe.com/payments/checkout-sessions-and-payment-intents-comparison.md).

Use o [Payment Element](https://docs.stripe.com/payments/payment-element.md) para incorporar um formulário de pagamento personalizado da Stripe e seu site ou aplicativo e oferecer formas de pagamento aos clientes. Para configurações avançadas e personalizações, consulte o guia de integração [Aceitar um Pagamento](https://docs.stripe.com/payments/accept-a-payment.md).

## Verificar a compatibilidade

**Localizações aceitas para empresas**: BR

**Moedas aceitas**: `brl`

**Moedas de apresentação**: `brl`

**Modo de pagamento**: Yes

**Modo de configuração**: No

**Modo de assinatura**: Yes

Uma Checkout Session deve atender a todas as seguintes condições para oferecer suporte a pagamentos com Boleto:

- Os preços de todos os produtos inclusos no checkout  precisam estar na mesma moeda. Se você tiver produtos em moedas diferentes, crie sessões do Checkout separadas para cada moeda.

## Configurar o servidor [Lado do servidor]

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 Checkout Session [Lado do servidor]

Adicione um endpoint ao seu servidor que cria uma [sessão do Checkout](https://docs.stripe.com/api/checkout/sessions/create.md) e retorna seu [segredo do cliente](https://docs.stripe.com/api/checkout/sessions/object.md#checkout_session_object-client_secret) 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.

Recomendamos usar [formas de pagamento dinâmicas](https://docs.stripe.com/payments/payment-methods/dynamic-payment-methods.md) para exibir dinamicamente as formas de pagamento elegíveis mais relevantes para cada cliente para maximizar a conversão. Você também pode [listar manualmente as formas de pagamento](https://docs.stripe.com/payments/payment-methods/integration-options.md#listing-payment-methods-manually), o que desabilita as formas de pagamento dinâmicas.

#### Gerencie formas de pagamento no Dashboard

#### TypeScript

```javascript
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: 'brl',
          product_data: {
            name: 'T-shirt',
          },
          unit_amount: 2000,
        },
        quantity: 1,
      },
    ],
    mode: 'payment',
    ui_mode: 'elements',
    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');
});
```

#### Listar manualmente as formas de pagamento

#### TypeScript

```javascript
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: 'brl',
          product_data: {
            name: 'T-shirt',
          },
          unit_amount: 2000,
        },
        quantity: 1,
      },
    ],
    mode: 'payment',
    ui_mode: 'elements',
    payment_method_types: ['boleto'],
    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]

#### 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 do Stripe.js incluindo a seguinte tag de script `<script src=“https://js.stripe.com/dahlia/stripe.js”></script>`. Saiba mais sobre [versões do Stripe.js](https://docs.stripe.com/sdks/stripejs-versioning.md).

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

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

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

#### 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@^5.0.0 @stripe/stripe-js@^8.0.0
```

Inicialize uma instância de `stripe` no frontend com sua chave publicável.

```javascript
import {loadStripe} from '@stripe/stripe-js';
const stripe = loadStripe("<<YOUR_PUBLISHABLE_KEY>>");
```

## 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
<div id="checkout-container"></div>
```

```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 (
    <CheckoutElementsProvider
      stripe={stripe}options={{clientSecret}}
    >
      <CheckoutForm />
    </CheckoutElementsProvider>
  );
};

export default App;
```

Acesse o objeto do [Checkout](https://docs.stripe.com/js/custom_checkout) no seu componente do formulário de checkout usando o hook `useCheckout()`. O objeto do `Checkout` contém dados da sessão de checkout 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 {useCheckout} from '@stripe/react-stripe-js/checkout';

const CheckoutForm = () => {const checkoutState = useCheckout();

  if (checkoutState.type === 'loading') {
    return (
      <div>Loading...</div>
    );
  }

  if (checkoutState.type === 'error') {
    return (
      <div>Error: {checkoutState.error.message}</div>
    );
  }

  return (
    <form>{JSON.stringify(checkoutState.checkout.lineItems, null, 2)}
      {/* A formatted total amount */}
      Total: {checkoutState.checkout.total.total.amount}
    </form>
  );
};
```

## Coletar e-mails do cliente [Lado do cliente]

#### HTML + JS

Ao concluir uma sessão do Checkout, é necessário fornecer um e-mail válido do cliente.

Essas instruções criam um campo de entrada de e‑mail e utilizam o método [updateEmail](https://docs.stripe.com/js/custom_checkout/update_email) do objeto `Checkout`.

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.
- Informe um e‑mail que você já tenha validado no [checkout.confirm](https://docs.stripe.com/js/custom_checkout/confirm).

```html
<input type="text" id="email" />
<div id="email-errors"></div>
```

```javascript
const checkout = stripe.initCheckoutElementsSdk({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;
      }
    });
  });
}
```

#### React

Ao concluir uma sessão do Checkout, é necessário fornecer um e-mail válido do cliente.

Essas instruções criam um campo de entrada de e‑mail e utilizam o método [updateEmail](https://docs.stripe.com/js/react_stripe_js/checkout/update_email) do objeto `Checkout`.

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.
- Informe um e‑mail que você já tenha validado no [confirm](https://docs.stripe.com/js/react_stripe_js/checkout/confirm).

```jsx
import React from 'react';
import {useCheckout} from '@stripe/react-stripe-js/checkout';

const EmailInput = () => {
  const checkoutState = useCheckout();
  const [email, setEmail] = React.useState('');
  const [error, setError] = React.useState(null);

  if (checkoutState.type === 'loading') {
    return (
      <div>Loading...</div>
    );
  } else if (checkoutState.type === 'error') {
    return (
      <div>Error: {checkoutState.error.message}</div>
    );
  }

  const handleBlur = () => {checkoutState.checkout.updateEmail(email).then((result) => {
      if (result.type === 'error') {
        setError(result.error);
      }
    })
  };

  const handleChange = (e) => {
    setError(null);
    setEmail(e.target.value);
  };

  return (
    <div>
      <label htmlFor="checkout-form-email">Email</label>
      <input
        id="checkout-form-email"
        type="email"
        value={email}
        onChange={handleChange}
        onBlur={handleBlur}
      />
      {error && <div>{error.message}</div>}
    </div>
  );
};

export default EmailInput;
```

## 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
<div id="payment-element"></div>
```

```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, useCheckout} from '@stripe/react-stripe-js/checkout';

const CheckoutForm = () => {
  const checkoutState = useCheckout();

  if (checkoutState.type === 'loading') {
    return (
      <div>Loading...</div>
    );
  }

  if (checkoutState.type === 'error') {
    return (
      <div>Error: {checkoutState.error.message}</div>
    );
  }

  return (
    <form>

      {JSON.stringify(checkoutState.checkout.lineItems, null, 2)}
      {/* A formatted total amount */}
      Total: {checkoutState.checkout.total.total.amount}
<PaymentElement options={{layout: 'accordion'}}/>
    </form>
  );
};

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

## Enviar 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
<button id="pay-button">Pay</button>
<div id="confirm-errors"></div>
```

```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 **Pagar** que chame [confirm](https://docs.stripe.com/js/custom_checkout/confirm) do [useCheckout](https://docs.stripe.com/js/react_stripe_js/checkout/use_checkout) para submeter o pagamento.

```jsx
import React from 'react';
import {useCheckout} from '@stripe/react-stripe-js/checkout';

const PayButton = () => {
  const checkoutState = useCheckout();
  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 (
    <div>
      <button disabled={!checkoutState.checkout.canConfirm || loading} onClick={handleClick}>
        Pay
      </button>
      {error && <div>{error.message}</div>}
    </div>
  )
};

export default PayButton;
```

## Testar sua integração

Para testar sua integração, escolha a forma de pagamento e toque em **Pay**. Em uma *área restrita* (A sandbox is an isolated test environment that allows you to test Stripe functionality in your account without affecting your live integration. Use sandboxes to safely experiment with new features and changes), isso o redirecionará para uma página de pagamento de teste, onde você poderá aprovar ou recusar o pagamento.

No modo ao vivo, ao tocar em **Pay**, você será redireciona para o site boleto — você não terá a opção de aprovar ou recusar o pagamento com o boleto.


# API Payment Intents

> This is a API Payment Intents for when payment-ui is elements and api-integration is paymentintents. View the full page at https://docs.stripe.com/payments/boleto/accept-a-payment?payment-ui=elements&api-integration=paymentintents.

Para determinar qual API atende melhor às necessidades do seu negócio, consulte o [guia de comparação](https://docs.stripe.com/payments/checkout-sessions-and-payment-intents-comparison.md).

Use o [Payment Element](https://docs.stripe.com/payments/payment-element.md) para incorporar um formulário de pagamento personalizado da Stripe e seu site ou aplicativo e oferecer formas de pagamento aos clientes. Para configurações avançadas e personalizações, consulte o guia de integração [Aceitar um Pagamento](https://docs.stripe.com/payments/accept-a-payment.md).

## Configurar a Stripe [Lado do servidor]

Para começar, [crie uma conta Stripe](https://dashboard.stripe.com/register).

Use nossas bibliotecas oficiais para acessar a API da Stripe no 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'
```

## Coletar dados de pagamento [Lado do cliente]

Está tudo pronto para você coletar dados de pagamento do cliente com o Payment Element. O Payment Element é um componente de IU pré-integrado 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.

O endereço da página de checkout deve começar com `https://` em vez de `http://` para que sua integração funcione. Você pode testar sua integração sem usar HTTPS, mas lembre-se de [habilitá-la](https://docs.stripe.com/security/guide.md#tls) quando estiver pronto para aceitar pagamentos em tempo real.

#### HTML + JS

### Configurar Stripe.js

O Payment Element está automaticamente disponível como um recurso do Stripe.js. Inclua o script Stripe.js em sua página de checkout adicionando-o ao `head` do arquivo HTML. Sempre carregue Stripe.js diretamente de js.stripe.com para manter a conformidade com PCI. Não inclua o script em um pacote nem hospede pessoalmente uma cópia dele.

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

Crie uma instância da Stripe com o seguinte JavaScript na sua página de checkout:

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

### Adicione o Payment Element à sua página de checkout

O Payment Element precisa de um lugar na sua página de checkout. Crie um nó do DOM vazio (contêiner) com um ID único no seu formulário de pagamento:

```html
<form id="payment-form">
  <div id="payment-element">
    <!-- Elements will create form elements here -->
  </div>
  <button id="submit">Submit</button>
  <div id="error-message">
    <!-- Display error message to your customers here -->
  </div>
</form>
```

#### Controlar formas de pagamento no Dashboard

Após carregar o formulário acima, crie uma instância do Elements com `mode`, `amount` e `currency`. Esses valores determinam quais formas de pagamento são vistas pelo cliente. Para informar uma nova forma de pagamento no formulário, habilite-a no [Dashboard](https://dashboard.stripe.com/settings/payment_methods).

```javascript
const options = {mode:'payment',
  amount:2000,
  currency: 'brl',
  // Fully customizable with appearance API.
  appearance: {/*...*/},
};

// Set up Stripe.js and Elements to use in checkout formconst elements = stripe.elements(options);

// Create and mount the Payment Element
const paymentElementOptions = { layout: 'accordion'};
const paymentElement = elements.create('payment', paymentElementOptions);
paymentElement.mount('#payment-element');
```

#### Listar manualmente as formas de pagamento

Para listar manualmente as formas de pagamento que você deseja disponibilizar, adicione cada uma delas a `paymentMethodTypes`.

Em seguida, crie uma instância do Payment Element e monte-a no nó DOM do contêiner.

```javascript
const options = {mode:'payment',
  amount:2000,
  currency: 'brl',
  paymentMethodTypes: ['boleto'],
  // Fully customizable with appearance API.
  appearance: {/*...*/},
};

// Set up Stripe.js and Elements to use in checkout formconst elements = stripe.elements(options);

// Create and mount the Payment Element
const paymentElementOptions = { layout: 'accordion'};
const paymentElement = elements.create('payment', paymentElementOptions);
paymentElement.mount('#payment-element');
```

#### React

### Configurar Stripe.js

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 npm.

```bash
npm install --save @stripe/react-stripe-js @stripe/stripe-js
```

### Adicione e configure o provedor do Elements na sua página de checkout

Para usar o componente Payment Element, encapsule o componente da página de checkout em um [provedor do Elements](https://docs.stripe.com/sdks/stripejs-react.md#elements-provider). Chame `loadStripe` com sua chave publicável e passe a `Promise` retornada para o provedor `Elements`.

#### Controlar formas de pagamento no Dashboard

O provedor do `Elements` também aceita `mode`, `amount` e `currency`. Esses valores determinam quais formas de pagamento são vistas pelo cliente. Para informar uma nova forma de pagamento no formulário, habilite-a no [Dashboard](https://dashboard.stripe.com/settings/payment_methods).

```jsx
import React from 'react';
import ReactDOM from 'react-dom';
import {Elements} from '@stripe/react-stripe-js';
import {loadStripe} from '@stripe/stripe-js';

import CheckoutForm from './CheckoutForm';

// Make sure to call `loadStripe` outside of a component’s render to avoid
// recreating the `Stripe` object on every render.
const stripePromise = loadStripe('<<YOUR_PUBLISHABLE_KEY>>');

function App() {
  const options = {mode:'payment',
    amount:2000,
    currency: 'brl',
    // Fully customizable with appearance API.
    appearance: {/*...*/},
  };

  return (
    <Elements stripe={stripePromise} options={options}>
      <CheckoutForm />
    </Elements>
  );
};

ReactDOM.render(<App />, document.getElementById('root'));
```

#### Listar manualmente as formas de pagamento

```jsx
import React from 'react';
import ReactDOM from 'react-dom';
import {Elements} from '@stripe/react-stripe-js';
import {loadStripe} from '@stripe/stripe-js';

import CheckoutForm from './CheckoutForm';

// Make sure to call `loadStripe` outside of a component’s render to avoid
// recreating the `Stripe` object on every render.
const stripePromise = loadStripe('<<YOUR_PUBLISHABLE_KEY>>');

function App() {
  const options = {mode:'payment',
    amount:2000,
    currency: 'brl',
    paymentMethodTypes: ['boleto'],
    // Fully customizable with appearance API.
    appearance: {/*...*/},
  };

  return (
    <Elements stripe={stripePromise} options={options}>
      <CheckoutForm />
    </Elements>
  );
};

ReactDOM.render(<App />, document.getElementById('root'));
```

### Adicione o componente Payment Element

Use o componente `PaymentElement` para criar seu formulário.

```jsx
import React from 'react';
import {PaymentElement} from '@stripe/react-stripe-js';

const CheckoutForm = () => {
  return (
    <form><PaymentElement />
      <button>Submit</button>
    </form>
  );
};

export default CheckoutForm;
```

É possível personalizar o Payment Element para corresponder ao design do seu site passando o [objeto appearance](https://docs.stripe.com/elements/appearance-api.md) em `options` na criação do provedor do `Elements`.

### Solicitar endereços

Por padrão, o Payment Element só recolhe os detalhes necessários do endereço de faturamento. Alguns comportamentos, como [calcular impostos](https://docs.stripe.com/api/tax/calculations/create.md) ou inserir detalhes de entrega, exigem o endereço completo do cliente. Você pode:

- Use o [Address Element](https://docs.stripe.com/elements/address-element.md) para aproveitar os recursos de autocompletar e traduzir para recolher o endereço completo do cliente. Isso ajuda a garantir um cálculo tributário mais preciso.
- Obtenha os detalhes do endereço usando seu próprio formulário personalizado.

## Criar um PaymentIntent [Lado do servidor]

> #### Execute uma lógica comercial personalizada imediatamente antes da confirmação do pagamento
> 
> Acesse a [etapa 5](https://docs.stripe.com/payments/finalize-payments-on-the-server.md?platform=web&type=payment#submit-payment) do guia de finalização de pagamentos para executar sua lógica de negócio personalizada imediatamente antes da confirmação do pagamento. Caso contrário, siga as etapas abaixo para ter uma integração mais simples, que usa `stripe.confirmPayment` no cliente para confirmar o pagamento e gerenciar as próximas ações.

#### Controlar formas de pagamento no Dashboard

Quando o cliente enviar seu formulário de pagamento, use um *PaymentIntent* (The Payment Intents API tracks the lifecycle of a customer checkout flow and triggers additional authentication steps when required by regulatory mandates, custom Radar fraud rules, or redirect-based payment methods) para facilitar o processo de confirmação e pagamento. Crie um PaymentIntent no seu servidor com `amount` e `currency`. Para evitar que clientes mal-intencionados escolham seus próprios preços, sempre decida quanto cobrar no lado do servidor (um ambiente confiável) e não no cliente.

Um `PaymentIntent` inclui um *segredo do cliente* (The client secret is a unique key returned from Stripe as part of a PaymentIntent. This key lets the client access important fields from the PaymentIntent (status, amount, currency) while hiding sensitive ones (metadata, customer)). Envie esse valor ao seu cliente para que o Stripe.js o utilize para concluir o processo de pagamento com segurança.

#### Accounts v2

#### Ruby

```ruby
require 'stripe'
Stripe.api_key = '<<YOUR_SECRET_KEY>>'

post '/create-intent' do
  intent = Stripe::PaymentIntent.create({
    # To allow saving and retrieving payment methods, provide the customer's Account ID.
    customer_account: "{{CUSTOMER_ACCOUNT_ID}}",
    amount: 2000,
    currency: 'brl',
  })
  {client_secret: intent.client_secret}.to_json
end
```

#### Clientes v1

#### Ruby

```ruby
require 'stripe'
Stripe.api_key = '<<YOUR_SECRET_KEY>>'

post '/create-intent' do
  intent = Stripe::PaymentIntent.create({
    # To allow saving and retrieving payment methods, provide the Customer ID.
    customer: customer.id,
    amount: 2000,
    currency: 'brl',
  })
  {client_secret: intent.client_secret}.to_json
end
```

#### Listar manualmente as formas de pagamento

Quando o cliente enviar seu formulário de pagamento, use um *PaymentIntent* (The Payment Intents API tracks the lifecycle of a customer checkout flow and triggers additional authentication steps when required by regulatory mandates, custom Radar fraud rules, or redirect-based payment methods) para facilitar o processo de confirmação e pagamento. Crie um PaymentIntent no seu servidor com `amount`, `currency` e uma ou mais formas de pagamento usando `payment_method_types`. Para evitar que clientes mal-intencionados escolham seus próprios preços, sempre decida quanto cobrar no lado do servidor (um ambiente confiável) e não no cliente.

Incluído em um PaymentIntent está um *segredo do cliente* (The client secret is a unique key returned from Stripe as part of a PaymentIntent. This key lets the client access important fields from the PaymentIntent (status, amount, currency) while hiding sensitive ones (metadata, customer)). Retorne esse valor ao cliente para que o Stripe.js possa usá-lo na conclusão do processo de pagamento com segurança.

#### Ruby

```ruby
require 'stripe'
Stripe.api_key = '<<YOUR_SECRET_KEY>>'

post '/create-intent' do
  intent = Stripe::PaymentIntent.create({
    # To allow saving and retrieving payment methods, provide the Customer ID.
    customer: customer.id,
    amount: 2000,
    currency: 'brl',
    payment_method_types: ['boleto'],
  })
  {client_secret: intent.client_secret}.to_json
end
```

## Enviar o pagamento para a Stripe [Lado do cliente]

Use [stripe.confirmPayment](https://docs.stripe.com/js/payment_intents/confirm_payment) para concluir o pagamento usando os detalhes do Payment Element.

Forneça um [return_url](https://docs.stripe.com/api/payment_intents/create.md#create_payment_intent-return_url) a essa função para indicar para onde a Stripe redireciona o usuário após a conclusão do pagamento. Seu usuário pode ser redirecionado inicialmente para um site intermediário, como uma página de autorização bancária, antes de ser redirecionado para `return_url`. Os pagamentos com cartão são redirecionados imediatamente para `return_url` quando um pagamento é finalizado.

Se não quiser redirecionar pagamentos com cartão após a conclusão do pagamento, defina [redirect](https://docs.stripe.com/js/payment_intents/confirm_payment#confirm_payment_intent-options-redirect) como `if_required`. Isso somente redireciona os clientes que fazem checkout com formas de pagamento baseadas em redirecionamento.

#### HTML + JS

```javascript

const form = document.getElementById('payment-form');
const submitBtn = document.getElementById('submit');

const handleError = (error) => {
  const messageContainer = document.querySelector('#error-message');
  messageContainer.textContent = error.message;
  submitBtn.disabled = false;
}

form.addEventListener('submit', async (event) => {
  // We don't want to let default form submission happen here,
  // which would refresh the page.
  event.preventDefault();

  // Prevent multiple form submissions
  if (submitBtn.disabled) {
    return;
  }

  // Disable form submission while loading
  submitBtn.disabled = true;

  // Trigger form validation and wallet collection
  const {error: submitError} = await elements.submit();
  if (submitError) {
    handleError(submitError);
    return;
  }

  // Create the PaymentIntent and obtain clientSecret
  const res = await fetch("/create-intent", {
    method: "POST",
  });

  const {client_secret: clientSecret} = await res.json();

  // Confirm the PaymentIntent using the details collected by the Payment Element
  const {error} = await stripe.confirmPayment({
    elements,
    clientSecret,
    confirmParams: {
      return_url: 'https://example.com/order/123/complete',
    },
  });

  if (error) {
    // This point is only reached if there's an immediate error when
    // confirming the payment. Show the error to your customer (for example, payment details incomplete)
    handleError(error);
  } else {
    // Your customer is redirected to your `return_url`. For some payment
    // methods like iDEAL, your customer is redirected to an intermediate
    // site first to authorize the payment, then redirected to the `return_url`.
  }
});

```

#### React

```jsx
import React, {useState} from 'react';
import {useStripe, useElements, PaymentElement} from '@stripe/react-stripe-js';

export default function CheckoutForm() {
  const stripe = useStripe();
  const elements = useElements();

  const [errorMessage, setErrorMessage] = useState();
  const [loading, setLoading] = useState(false);

  const handleError = (error) => {
    setLoading(false);
    setErrorMessage(error.message);
  }

  const handleSubmit = async (event) => {
    // We don't want to let default form submission happen here,
    // which would refresh the page.
    event.preventDefault();

    if (!stripe) {
      // Stripe.js hasn't yet loaded.
      // Make sure to disable form submission until Stripe.js has loaded.
      return;
    }

    setLoading(true);

    // Trigger form validation and wallet collection
    const {error: submitError} = await elements.submit();
    if (submitError) {
      handleError(submitError);
      return;
    }

    // Create the PaymentIntent and obtain clientSecret
    const res = await fetch("/create-intent", {
      method: "POST",
    });

    const {client_secret: clientSecret} = await res.json();

    // Confirm the PaymentIntent using the details collected by the Payment Element
    const {error} = await stripe.confirmPayment({
      elements,
      clientSecret,
      confirmParams: {
        return_url: 'https://example.com/order/123/complete',
      },
    });

    if (error) {
      // This point is only reached if there's an immediate error when
      // confirming the payment. Show the error to your customer (for example, payment details incomplete)
      handleError(error);
    } else {
      // Your customer is redirected to your `return_url`. For some payment
      // methods like iDEAL, your customer is redirected to an intermediate
      // site first to authorize the payment, then redirected to the `return_url`.
    }
  };

  return (
    <form onSubmit={handleSubmit}>
      <PaymentElement />
      <button type="submit" disabled={!stripe || loading}>
        Submit Payment
      </button>
      {errorMessage && <div>{errorMessage}</div>}
    </form>
  );
}
```

## Optional: Processar eventos pós-pagamento

Stripe envia um evento [payment_intent.succeeded](https://docs.stripe.com/api/events/types.md#event_types-payment_intent.succeeded) quando o pagamento é concluído. Use o Dashboard, um *webhook* (A webhook is a real-time push notification sent to your application as a JSON payload through HTTPS requests) personalizado ou uma solução de parceiros para receber esses eventos e executar ações, como enviar um e-mail de confirmação de pedido ao cliente, registrar a venda em um banco de dados ou iniciar um fluxo de entrega.

Escute esses eventos em vez de aguardar um retorno de chamada do cliente. No cliente, o consumidor pode fechar a janela do navegador ou sair do aplicativo antes da execução do retorno de chamada, o que permite que clientes mal-intencionados manipulem a resposta. Configurar a integração para escutar eventos assíncronos também ajuda a aceitar mais formas de pagamento no futuro. Conheça as [diferenças entre todas as formas de pagamento aceitas](https://stripe.com/payments/payment-methods-guide).

- **Tratar eventos manualmente no Dashboard**

  Use o Dashboard para [visualizar seus pagamentos de teste no Dashboard](https://dashboard.stripe.com/test/payments), enviar recibos por e-mail, lidar com repasses ou tentar novamente pagamentos que falharam.

- **Crie um webhook personalizado**

  [Build a custom webhook](https://docs.stripe.com/webhooks/handling-payment-events.md#build-your-own-webhook) handler to listen for events and build custom asynchronous payment flows. Test and debug your webhook integration locally with the Stripe CLI.

- **Integrar um aplicativo pré-criado**

  Lide com eventos comuns da empresa, como [automação](https://stripe.partners/?f_category=automation) ou [marketing e vendas](https://stripe.partners/?f_category=marketing-and-sales), integrando um aplicativo de parceiros.

## Testar sua integração

Para testar sua integração, escolha a forma de pagamento e toque em **Pay**. Em uma *área restrita* (A sandbox is an isolated test environment that allows you to test Stripe functionality in your account without affecting your live integration. Use sandboxes to safely experiment with new features and changes), isso o redirecionará para uma página de pagamento de teste, onde você poderá aprovar ou recusar o pagamento.

No modo ao vivo, ao tocar em **Pay**, você será redireciona para o site boleto — você não terá a opção de aprovar ou recusar o pagamento com o boleto.

## Códigos de erro

Esta tabela detalha os códigos de erro comuns e as ações recomendadas:

| Código de erro                                            | Ação recomendada                                                                                                                                                                                                                                                                                                                                                                      |
| --------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `payment_intent_invalid_currency`                         | Insira uma moeda aceita.                                                                                                                                                                                                                                                                                                                                                              |
| `missing_required_parameter`                              | Verifique a mensagem de erro para obter mais informações sobre o parâmetro exigido.                                                                                                                                                                                                                                                                                                   |
| `payment_intent_payment_attempt_failed`                   | Esse código pode aparecer no campo [last_payment_error.code](https://docs.stripe.com/api/payment_intents/object.md#payment_intent_object-last_payment_error-code) de um PaymentIntent. Verifique a mensagem de erro para obter um motivo de falha detalhado e sugestões sobre o tratamento de erros.                                                                                  |
| `payment_intent_authentication_failure`                   | Este código pode aparecer no campo [last_payment_error.code](https://docs.stripe.com/api/payment_intents/object.md#payment_intent_object-last_payment_error-code) de um PaymentIntent. Verifique a mensagem de erro para obter um motivo detalhado da falha e sugestões de como lidar com o erro. Este erro ocorre quando você aciona manualmente uma falha ao testar sua integração. |
| `payment_intent_redirect_confirmation_without_return_url` | Informe um `return_url` quando confirmar um PaymentIntent.                                                                                                                                                                                                                                                                                                                            |


# Direct API

> This is a Direct API for when payment-ui is direct-api. View the full page at https://docs.stripe.com/payments/boleto/accept-a-payment?payment-ui=direct-api.

Os usuários da Stripe no Brasil podem receber pagamentos por boleto dos clientes brasileiros por meio das APIs Payment Intents e Payment Methods. O boleto tem um número exclusivo, que o *cliente* (Customer objects represent customers of your business. They let you reuse payment methods and give you the ability to track multiple payments) usa para fazer o pagamento em caixas eletrônicos, bancos, internet banking ou agências autorizadas.

## Configurar a Stripe [Lado do servidor]

Primeiro, você precisa de uma conta Stripe. [Cadastre-se aqui](https://dashboard.stripe.com/register).

Use nossas bibliotecas oficiais para acessar a API da Stripe no 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 um PaymentIntent [Lado do servidor]

A Stripe usa um objeto [PaymentIntent](https://docs.stripe.com/api/payment_intents.md) para representar sua intenção de coletar o pagamento de um cliente, acompanhando desde a criação do boleto até seu pagamento.

Crie um PaymentIntent no seu servidor com um valor e a moeda `brl` (o Boleto não aceita outras moedas). Se você já tiver uma integração usando a [API Payment Intents](https://docs.stripe.com/payments/payment-intents.md), adicione `boleto` à lista de [tipos de forma de pagamento](https://docs.stripe.com/api/payment_intents/create.md#create_payment_intent-payment_method_types) para o seu `PaymentIntent`.

O PaymentIntent retornado contém um *segredo do cliente* (The client secret is a unique key returned from Stripe as part of a PaymentIntent. This key lets the client access important fields from the PaymentIntent (status, amount, currency) while hiding sensitive ones (metadata, customer)), que você usa para finalizar o processo de pagamento com segurança. Devolva o segredo do cliente ao cliente para usá-lo nas próximas etapas.

```curl
curl https://api.stripe.com/v1/payment_intents \
  -u "<<YOUR_SECRET_KEY>>:" \
  -d amount=1099 \
  -d currency=brl \
  -d "payment_method_types[]=boleto"
```

### Outras opções da forma de pagamento

Você pode especificar um parâmetro opcional `expires_after_days` nas [opções da forma de pagamento](https://docs.stripe.com/api/payment_intents/create.md#create_payment_intent-payment_method_options-boleto-expires_after_days) para o `PaymentIntent`, definindo os dias corridos até o vencimento. Por exemplo, se você criar um boleto na segunda-feira e a configuração de `expires_after_days` for 2, o boleto vencerá na quarta-feira, às 23h59, horário Sao_Paulo (UTC-3). Se a configuração for 0, o boleto vencerá no final do dia. O parâmetro `expires_after_days` pode ser de 0 a 60 dias. O padrão é 3 dias. Você pode personalizar os dias de validade padrão na sua conta nas [configurações de formas de pagamento](https://dashboard.stripe.com/settings/payment_methods)

## Coletar dados da forma de pagamento [Lado do cliente]

Crie um formulário para obter os dados necessários para cobrar o cliente:

| Campo         | Valor                                                                                                                                                                                                                                                           |
| ------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `name`        | Nome completo do cliente.                                                                                                                                                                                                                                       |
| `email`       | Endereço de e-mail do cliente.                                                                                                                                                                                                                                  |
| `tax_id`      | O CPF (para indivíduos) ou CNPJ (para empresas) do cliente. O CPF precisa ter 11 dígitos em um dos seguintes formatos: `000.000.000-00` ou `00000000000`. O CNPJ precisa ter 14 dígitos em um dos seguintes formatos: `00.000.000/0000-00` ou `00000000000000`. |
| `address`     | Nome da rua e número do endereço do cliente.                                                                                                                                                                                                                    |
| `city`        | Cidade do endereço do cliente.                                                                                                                                                                                                                                  |
| `state`       | Sigla com duas letras representando o estado brasileiro ([ISO_3166-2:BR](https://en.wikipedia.org/wiki/ISO_3166-2:BR)) do endereço do cliente.                                                                                                                  |
| `postal_code` | CEP do endereço do cliente, com dois formatos possíveis: `XXXXX-XXX` ou `XXXXXXXX`.                                                                                                                                                                             |

> Os campos `name`, `address`, `city` (nome, endereço, cidade) devem conter no mínimo um caractere alfanumérico do [Basic Latin (ASCII) Unicode Block](https://en.wikipedia.org/wiki/Basic_Latin_\(Unicode_block\)).

```html
<form id="payment-form">
  <div class="form-row">
    <label for="name">
      Name
    </label>
    <input id="name" name="name" required>
  </div>

  <div class="form-row">
    <label for="tax_id">
      CPF/CNPJ
    </label>
    <input id="tax_id" name="tax_id" required>
  </div>

  <div class="form-row">
    <label for="email">
      Email
    </label>
    <input id="email" name="email" required>
  </div>

  <div class="form-row">
    <label for="address">
      Address
    </label>
    <input id="address" name="address" required>
  </div>

  <div class="form-row">
    <label for="city">
      City
    </label>
    <input id="city" name="city" required>
  </div>

  <div class="form-row">
    <label for="state">
      State
    </label>
    <input id="state" name="state" required>
  </div>

  <div class="form-row">
    <label for="postal_code">
      Postal Code
    </label>
    <input id="postal_code" name="postal_code" required>
  </div>

  <!-- Used to display form errors. -->
  <div id="error-message" role="alert"></div>

  <button id="submit-button">Pay with Boleto</button>
</form>
```

## Enviar o pagamento para a Stripe [Lado do cliente]

Quando o cliente optar por pagar com Boleto, use Stripe.js para enviar o pagamento à Stripe. [Stripe.js](https://docs.stripe.com/payments/elements.md) é a nossa biblioteca principal de JavaScript para criação de fluxos de pagamento.

Inclua Stripe.js na sua página de checkout, adicionando o script ao `head` do seu arquivo HTML.

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

Crie uma instância de Stripe.js com o seguinte JavaScript em sua página de checkout:

```javascript
// Set your publishable key. Remember to switch to your live publishable key in production!
// See your keys here: https://dashboard.stripe.com/apikeys
const stripe = Stripe('<<YOUR_PUBLISHABLE_KEY>>');
```

Use [stripe.confirmBoletoPayment](https://docs.stripe.com/js/payment_intents/confirm_boleto_payment) e o [segredo do cliente](https://docs.stripe.com/api/payment_intents/object.md#payment_intent_object-client_secret) do objeto `PaymentIntent` criado na etapa 2 para enviar os dados de cobrança do cliente.

Depois da confirmação, a Stripe abre automaticamente um modal que mostra o boleto ao cliente.

```javascript
var form = document.getElementById('payment-form');

form.addEventListener('submit', async (event) => {
  event.preventDefault();

  const result = await stripe.confirmBoletoPayment(
    '{{PAYMENT_INTENT_CLIENT_SECRET}}',
    {
      payment_method: {
        boleto: {
          tax_id: document.getElementById('tax_id').value,
        },
        billing_details: {
          name: document.getElementById('name').value,
          email: document.getElementById('email').value,
          address: {
            line1: document.getElementById('address').value,
            city: document.getElementById('city').value,
            state: document.getElementById('state').value,
            postal_code: document.getElementById('postal_code').value,
            country: 'BR',
          },
        },
      },
    }
  );
  // Stripe.js will open a modal to display the Boleto voucher to your customer
  // This async function finishes when the customer closes the modal

  if (result.error) {
    // Display error to your customer
    const errorMsg = document.getElementById('error-message');
    errorMsg.innerText = result.error.message;
  }
});
```

> `stripe.confirmBoletoPayment` pode levar vários segundos para finalizar. Nesse período, previna que o formulário seja reenviado e apresente um indicador de espera, como um spinner. Se receber um erro, mostre-o ao cliente, reative o formulário e oculte o spinner.

Quando uma guia de boleto é devidamente criada, o valor da propriedade `status` do PaymentIntent retornado é `requires_action`. Verifique o status de um PaymentIntent no [Dashboard](https://dashboard.stripe.com/test/payments) ou inspecionando a propriedade status no objeto. Se a guia do boleto não for devidamente criada, inspecione o `error` retornado para determinar a causa (por exemplo, formato de e-mail inválido).

### Opcional: enviar um e-mail ao cliente com um link para o boleto

A Stripe envia um evento [payment_intent.requires_action](https://docs.stripe.com/api/events/types.md#event_types-payment_intent.requires_action) quando um boleto é criado. Para enviar um e-mail ao cliente com o link para o boleto, pode localizar o link `hosted_voucher_url` em [payment_intent.next_action.boleto_display_details](https://docs.stripe.com/api/payment_intents/object.md#payment_intent_object-next_action-boleto_display_details-hosted_voucher_url).

### Opcional: personalizar o boleto

A Stripe permite personalizar as IUs exibidas para seus clientes na página [Configurações da marca](https://dashboard.stripe.com/account/branding).

Estas configurações de marca podem ser aplicadas à guia:

- **Ícone**: a imagem de sua marca e nome fantasia da empresa
- **Cor de destaque**: usada no botão Copiar número
- **Cor da marca**: usada como cor de fundo

## Processar eventos pós-pagamento [Lado do servidor]

Os pagamentos por boleto são assíncronos, ou seja, os fundos não ficam disponíveis imediatamente. O cliente pode não pagar o boleto imediatamente após o checkout.

A Stripe envia um evento [payment_intent.succeeded](https://docs.stripe.com/api/events/types.md#event_types-payment_intent.succeeded) no dia útil seguinte (de segunda a sexta, exceto feriados do calendário brasileiro) para todos os boletos pagos. Use o Dashboard ou um *webhook* (A webhook is a real-time push notification sent to your application as a JSON payload through HTTPS requests) personalizado para receber esses eventos e executar ações (por exemplo, enviar um e-mail de confirmação de pedido ao cliente, registrar a venda em um banco de dados ou iniciar um fluxo de entrega).

Se uma guia de boleto não for paga antes das 23h59 America/Sao_Paulo (UTC-3) do dia do vencimento, a Stripe enviará um evento [payment_intent.payment_failed](https://docs.stripe.com/api/events/types.md#event_types-payment_intent.payment_failed) após 1 dia útil. Por exemplo, se uma guia de boleto vencer na quinta-feira, o evento será enviado na sexta-feira. Se uma guia de boleto expirar na sexta-feira, o evento será enviado na segunda-feira seguinte.

| Evento                          | Descrição                                                 | Próximas etapas                                                                                    |
| ------------------------------- | --------------------------------------------------------- | -------------------------------------------------------------------------------------------------- |
| `payment_intent.succeeded`      | O cliente pagou o boleto antes do vencimento.             | Execute o pedido de mercadorias ou serviços do cliente.                                            |
| `payment_intent.payment_failed` | O cliente não pagou a guia de boleto antes do vencimento. | Entre em contato com o cliente por e-mail ou notificação push e solicite outra forma de pagamento. |

## Testar a integração

Em uma *área restrita* (A sandbox is an isolated test environment that allows you to test Stripe functionality in your account without affecting your live integration. Use sandboxes to safely experiment with new features and changes), defina `payment_method.billing_details.email` de acordo com os valores a seguir ao chamar [stripe.confirmBoletoPayment](https://docs.stripe.com/js/payment_intents/confirm_boleto_payment) para testar diferentes cenários.

| E-mail                                         | Descrição                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| ---------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `{any_prefix}@{any_domain}`                    | Simula um boleto pago pelo cliente depois de 3 minutos, com o webhook `payment_intent.succeeded` recebido depois de cerca de 3 minutos. Em produção, este webhook chega 1&nbsp;dia útil após o pagamento.

  Exemplo: fulaninho@exemplo.com.br                                                                                                                                                                                                                                                                                                                                                                                                          |
| `{any_prefix}succeed_immediately@{any_domain}` | Simula um boleto pago imediatamente pelo cliente, com o webhook `payment_intent.succeeded` recebido depois de alguns segundos. Em produção, este webhook chega 1&nbsp;dia útil após o pagamento.

  Exemplo: succeed_immediately@exemplo.com.br                                                                                                                                                                                                                                                                                                                                                                                                         |
| `{any_prefix}expire_immediately@{any_domain}`  | Simula um boleto que vence sem ser pago pelo cliente, com o webhook `payment_intent.payment_failed` recebido depois de alguns segundos.

  O campo `expires_at` em [next_action.boleto_display_details](https://docs.stripe.com/api/payment_intents/object.md#payment_intent_object-next_action-boleto_display_details-expires_at) está configurado para o horário atual, independente da configuração do parâmetro `expires_after_days` em [opções de forma de pagamento](https://docs.stripe.com/api/payment_intents/create.md#create_payment_intent-payment_method_options-boleto-expires_after_days).

  Exemplo: expire_immediately@exemplo.com.br |
| `{any_prefix}expire_with_delay@{any_domain}`   | Simula um boleto que vence sem ser pago pelo cliente, com o webhook `payment_intent.payment_failed` recebido depois de 3 minutos.

  O campo `expires_at` em [next_action.boleto_display_details](https://docs.stripe.com/api/payment_intents/object.md#payment_intent_object-next_action-boleto_display_details-expires_at) está configurado para 3 minutos no futuro, independente da configuração do parâmetro `expires_after_days` em [opções de forma de pagamento](https://docs.stripe.com/api/payment_intents/create.md#create_payment_intent-payment_method_options-boleto-expires_after_days).

  Exemplo: expire_with_delay@exemplo.com.br    |
| `{any_prefix}fill_never@{any_domain}`          | Simula um boleto que nunca é pago; ele expira de acordo com o campo `expires_at` em [next_action.boleto_display_details](https://docs.stripe.com/api/payment_intents/object.md#payment_intent_object-next_action-boleto_display_details-expires_at) de acordo com os parâmetros informados em [opções de forma de pagamento](https://docs.stripe.com/api/payment_intents/create.md#create_payment_intent-payment_method_options-boleto-expires_after_days). O webhook `payment_intent.payment_failed` é recebido em seguida.

  Exemplo: fill_never@exemplo.com.br                                                                                      |

| Código Fiscal                                     | Descrição                                                                                                 |
| ------------------------------------------------- | --------------------------------------------------------------------------------------------------------- |
| CPF `000.000.000-00`

  CNPJ `00.000.000/0000-00` | Em uma área restrita, defina `tax_id` como esses valores, para que eles ignorem a validação do ID fiscal. |

## Optional: Crie sua própria interface de boletos [Lado do cliente]

Recomendamos usar o arquivo Stripe.js para exibir o boleto com `confirmBoletoPayment`. Mas você também pode exibir o boleto aos clientes manualmente.

Para indicar que você vai gerenciar a próxima ação para exibir os dados do boleto ao seu cliente, especifique `handleActions: false` ao chamar stripe.confirmBoletoPayment na etapa 4.

```javascript
var form = document.getElementById('payment-form');

form.addEventListener('submit', async (event) => {
  event.preventDefault();

  const result = await stripe.confirmBoletoPayment(
    '{{PAYMENT_INTENT_CLIENT_SECRET}}',
    {
      payment_method: {
        boleto: {
          tax_id: document.getElementById('tax_id').value,
        },
        billing_details: {
          name: document.getElementById('name').value,
          email: document.getElementById('email').value,
          address: {
            line1: document.getElementById('address').value,
            city: document.getElementById('city').value,
            state: document.getElementById('state').value,
            postal_code: document.getElementById('postal_code').value,
            country: 'BR',
          },
        },
      },
    }, {handleActions: false},
  );
  if (result.error) {
    // Display error to your customer
    const errorMsg = document.getElementById('error-message');
    errorMsg.innerText = result.error.message;
  } else {
    // An Boleto voucher was successfully created
    const amount = result.paymentIntent.amount;
    const currency = result.paymentIntent.currency;

    const details = result.paymentIntent.next_action.boleto_display_details;
    const number = details.number;
    const expires_at = details.expires_at;

    // Handle the next action by displaying the Boleto details to your customer

    // You can also use the generated hosted voucher
    const hosted_voucher_url = details.hosted_voucher_url;
  }
});
```

Incluir, no mínimo, o seguinte:

| Detalhe            | Descrição                                                                                                                                                                                                                                                                                                                  |
| ------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Número             | Exiba o número do boleto de forma que o cliente possa copiá-lo facilmente para a área de transferência. Localize o número no objeto `PaymentIntent` em [next_action.boleto_display_details.number](https://docs.stripe.com/api/payment_intents/object.md#payment_intent_object-next_action-boleto_display_details-number). |
| Data de vencimento | Exiba a data de vencimento do boleto. Localize o carimbo de data e hora UNIX para vencimento do boleto no `PaymentIntent` em [next_action.boleto_display_details.expires_at](https://docs.stripe.com/api/payment_intents/object.md#payment_intent_object-next_action-boleto_display_details-expires_at).                   |
| Baixar PDF         | Exiba um botão para download que permite que o cliente baixe o boleto em PDF. O PDF do boleto que o cliente pode baixar fica no `PaymentIntent`, em [next_action.boleto_display_details.pdf](https://docs.stripe.com/api/payment_intents/object.md#payment_intent_object-next_action-boleto_display_details-pdf).          |

## Optional: Confirmar Payment Intent no lado do servidor [Lado do servidor]

Recomendamos o arquivo Stripe.js para *confirmar* (Confirming an intent indicates that the customer intends to use the current or provided payment method. Upon confirmation, the intent attempts to initiate the portions of the flow that have real-world side effects) um Payment Intent com boleto usando `confirmBoletoPayment`. O arquivo Stripe.js facilita a extensão da sua integração para outras formas de pagamento. No entanto, você também pode confirmar um Payment Intent no lado do servidor da seguinte maneira:

```curl
curl https://api.stripe.com/v1/payment_intents \
  -u "<<YOUR_SECRET_KEY>>:" \
  -d amount=1099 \
  -d currency=brl \
  -d confirm=true \
  -d "payment_method_types[]=boleto" \
  -d "payment_method_data[type]=boleto" \
  -d "payment_method_data[billing_details][name]=João da Silva" \
  --data-urlencode "payment_method_data[billing_details][email]=joao@exemplo.com" \
  -d "payment_method_data[billing_details][address][line1]=1234 Av. Paulista" \
  -d "payment_method_data[billing_details][address][city]=São Paulo" \
  -d "payment_method_data[billing_details][address][state]=SP" \
  -d "payment_method_data[billing_details][address][postal_code]=01310-000" \
  -d "payment_method_data[billing_details][address][country]=BR" \
  -d "payment_method_data[boleto][tax_id]=000.000.000-00"
```

## Optional: Enviar e-mails de instrução de pagamento

Você pode habilitar e-mails com instruções de pagamento do boleto na página [Configurações de e-mail](https://dashboard.stripe.com/settings/emails) no Dashboard. Após a habilitação, a Stripe envia e-mails com instruções de pagamento na confirmação do PaymentIntent. Os e-mails contêm o número do boleto e um link para a página do boleto hospedada na Stripe.

> Nos ambientes de teste, os e-mails com instruções só são enviados para endereços de e-mail vinculados à conta Stripe.

## Validade e cancelamento

Os boletos vencem após a data UNIX `expires_at`, e o cliente não pode pagar um boleto vencido. Não é possível cancelar um boleto antes do vencimento.

Depois do vencimento do boleto, o status do PaymentIntent muda para `requires_payment_method`. Neste ponto, você pode confirmar o PaymentIntent com outra forma de pagamento ou cancelar.