# Crie cobranças diretas
Crie cobranças diretamente na conta conectada e receba tarifas.
Crie *cobranças diretas* quando os clientes fazem transações diretamente com uma conta conectada e muitas vezes nem percebem a existência da sua plataforma. Com cobranças diretas:
- O pagamento aparece como cobrança na conta conectada, e não na conta da sua plataforma.
- O saldo da conta conectada aumenta a cada cobrança.
- O saldo da sua conta aumenta com as tarifas da plataforma de cada cobrança.
Esse tipo de cobrança é mais adequado para plataformas que fornecem software como serviço. A Shopify, por exemplo, oferece ferramentas para a criação de lojas online e a Worksify permite que professores vendam cursos online.
## Limitações de visibilidade da plataforma
O Direct Charges têm visibilidade limitada no nível da plataforma. Quando você cria uma cobrança direta:
- Elementos de transação como `PaymentIntents` e `Charges` existem na conta conectada, não na plataforma.
- Para acessar os dados de cobrança direta, você deve consultar a API da Stripe usando o ID da conta conectada [no cabeçalho Stripe-Account](https://docs.stripe.com/connect/authentication.md).
Esse comportamento de escopo afeta os serviços de sincronização de dados, como o Fivetran, bem como outras integrações de terceiros que dependem de consultas à API no nível da plataforma. Para recuperar dados de cobrança direta, eles devem consultar a conta conectada, não a plataforma.
> Recomendamos usar cobranças diretas para contas conectadas que têm acesso ao Stripe Dashboard completo.
Redirecione para uma página de pagamento hospedada pela Stripe usando o [Stripe Checkout](https://docs.stripe.com/payments/checkout.md). [Compare esta integração com as outras formas de integração da Stripe](https://docs.stripe.com/payments/online-payments.md#compare-features-and-availability).
#### Esforço de integração
Complexity: 2/5
#### Tipo de integração
Redirecionar para a página de pagamento hospedada pela Stripe
#### Personalização da IU
Personalização limitada
- 20 fontes predefinidas
- 3 raios de borda predefinidos
- Cores do fundo e das bordas personalizadas
- Logotipo personalizado
[Experimente](https://checkout.stripe.dev/)
Primeiro, [cadastre-se](https://dashboard.stripe.com/register) para obter uma conta Stripe.
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 uma sessão do Checkout [Lado do cliente] [Lado do servidor]
Uma [Sessão do Checkout](https://docs.stripe.com/api/checkout/sessions.md) controla o que o seu cliente vê no formulário de pagamento, como itens de linha, o valor do pedido e a moeda. Adicione um botão de checkout ao seu site para chamar um endpoint no lado do servidor e criar uma Sessão do Checkout.
```html
Checkout
```
No seu servidor, crie uma sessão do Checkout e redirecione o cliente para o [URL](https://docs.stripe.com/api/checkout/sessions/object.md#checkout_session_object-url) retornado na resposta.
```curl
curl https://api.stripe.com/v1/checkout/sessions \
-u "<>:" \
-H "Stripe-Account: {{CONNECTEDACCOUNT_ID}}" \
-d "line_items[0][price_data][currency]"=usd \
-d "line_items[0][price_data][product_data][name]"=T-shirt \
-d "line_items[0][price_data][unit_amount]"=1000 \
-d "line_items[0][quantity]"=1 \
-d "payment_intent_data[application_fee_amount]"=123 \
-d mode=payment \
--data-urlencode success_url="https://example.com/success?session_id={CHECKOUT_SESSION_ID}"
```
- `Stripe-Account`: este cabeçalho indica uma cobrança direta para sua conta conectada. A [marca](https://docs.stripe.com/connect/direct-charges.md#branding) da conta conectada é usada no Checkout, o que permite que os clientes tenham a sensação de interagir diretamente com a conta conectada em vez de com sua plataforma.
- `line_items`: este atributo representa os itens que o cliente está comprando e é exibido na página de checkout hospedada pela Stripe.
- `payment_intent_data[application_fee_amount]`: este atributo especifica o valor que sua plataforma deduz da transação como tarifa da plataforma. Depois que o pagamento é processado na conta conectada, o `application_fee_amount` é transferido para a plataforma. Consulte [coletar tarifas](https://docs.stripe.com/connect/direct-charges.md#collect-fees) para obter mais informações.
- `success_url`: a Stripe redireciona o cliente para a URL de sucesso depois que ele conclui um pagamento e substitui a string `{CHECKOUT_SESSION_ID}` pelo ID da sessão de checkout. Use isso para recuperar a sessão de checkout e inspecionar o status para decidir o que mostrar ao cliente. Você também pode acrescentar seus próprios parâmetros de consulta, que persistem durante o processo de redirecionamento. Consulte [como personalizar o comportamento de redirecionamento em uma página hospedada pela Stripe](https://docs.stripe.com/payments/checkout/custom-success-page.md) para obter mais informações.
Veja as cobranças criadas na sua conta conectada na sua [lista de pagamentos](https://dashboard.stripe.com/test/payments). Direct Charges não aparecem nas exportações, mas você pode encontrá-las em [relatórios](https://docs.stripe.com/stripe-reports.md), [Sigma](https://docs.stripe.com/stripe-data/sigma.md) ou usando a API.
## Gerenciar eventos pós-pagamento [Lado do servidor]
A Stripe envia um evento [checkout.session.completed](https://docs.stripe.com/api/events/types.md#event_types-checkout.session.completed) quando o pagamento é concluído. [Use um webhook para receber esses eventos](https://docs.stripe.com/webhooks/quickstart.md) 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 poderia fechar a janela do navegador ou sair do aplicativo antes da execução do retorno de chamada. Algumas formas de pagamento também demoram de 2 a 14 dias para a confirmação do pagamento. Configurar sua integração para escutar eventos assíncronos é o que permite a você aceitar diferentes tipos de [formas de pagamento](https://stripe.com/payments/payment-methods-guide) com uma única integração.
A Stripe recomenda gerenciar todos os eventos a seguir ao receber pagamentos com o Checkout:
| Evento | Descrição | Próximas etapas |
| -------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------ | ------------------------------------------------------------------------------------ |
| [checkout.session.completed](https://docs.stripe.com/api/events/types.md#event_types-checkout.session.completed) | O cliente autorizou o pagamento enviando o formulário do Checkout. | Aguarde a confirmação ou falha do pagamento. |
| [checkout.session.async_payment_succeeded](https://docs.stripe.com/api/events/types.md#event_types-checkout.session.async_payment_succeeded) | O pagamento do cliente foi confirmado. | Execute o pedido de mercadorias ou serviços. |
| [checkout.session.async_payment_failed](https://docs.stripe.com/api/events/types.md#event_types-checkout.session.async_payment_failed) | O pagamento foi recusado ou houve outro erro. | Entre em contato com o cliente por e-mail e solicite a realização de um novo pedido. |
Todos esses eventos incluem o objeto [Checkout Session](https://docs.stripe.com/api/checkout/sessions.md). Após o pagamento, o [status](https://docs.stripe.com/payments/paymentintents/lifecycle.md) subjacente do *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) muda de `processing` para `succeeded` ou um status malsucedido.
## Testar a integração
#### Cartões
| Número do cartão | Cenário | Como testar |
| ------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------- |
| 4242424242424242 | O pagamento com cartão é bem-sucedido e não precisa de autenticação. | Preencha o formulário do cartão de crédito usando o número do cartão de crédito com qualquer validade, CVC e código postal. |
| 4000002500003155 | O pagamento com cartão precisa de *autenticação* (Strong Customer Authentication (SCA) is a regulatory requirement in effect as of September 14, 2019, that impacts many European online payments. It requires customers to use two-factor authentication like 3D Secure to verify their purchase). | Preencha o formulário do cartão de crédito usando o número do cartão de crédito com qualquer validade, CVC e código postal. |
| 4000000000009995 | O cartão é recusado com um código de recusa como `insufficient_funds`. | Preencha o formulário do cartão de crédito usando o número do cartão de crédito com qualquer validade, CVC e código postal. |
| 6205500000000000004 | O cartão UnionPay tem um comprimento variável de 13 a 19 dígitos. | Preencha o formulário do cartão de crédito usando o número do cartão de crédito com qualquer validade, CVC e código postal. |
#### Carteiras
| Forma de pagamento | Cenário | Como testar |
| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Alipay | O cliente paga com uma forma de pagamento baseada em redirecionamento e [notificação imediata](https://docs.stripe.com/payments/payment-methods.md#payment-notification). | Escolha qualquer forma de pagamento baseada em redirecionamento, preencha os dados obrigatórios e confirme o pagamento. Em seguida, clique em **Concluir o pagamento de teste** na página de redirecionamento. |
#### Débito bancário autenticado
| Forma de pagamento | Cenário | Como testar |
| ------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Débito automático BECS | O cliente paga com débito automático BECS. | Preencha o formulário usando o número de conta `900123456` e BSB `000000`. Inicialmente, o status do PaymentIntent muda para `processing` e, 3 minutos depois, para `succeeded`. |
| Débito automático BECS | O pagamento do cliente falha com um código de erro `account_closed`. | Preencha o formulário usando o número da conta `111111113` e BSB `000000`. |
| Bancontact, EPS, iDEAL, e Przelewy24 | Seu cliente não faz a autenticação na página de redirecionamento de uma forma de pagamento baseada em redirecionamento e notificação imediata. | Escolha qualquer forma de pagamento baseada em redirecionamento, preencha os dados obrigatórios e confirme o pagamento. Em seguida, clique em **Falhar pagamento de teste** na página de redirecionamento. |
| Pay by Bank | O cliente paga com uma forma de pagamento baseada em redirecionamento e [notificação posterior](https://docs.stripe.com/payments/payment-methods.md#payment-notification). | Escolha a forma de pagamento, preencha os dados obrigatórios e confirme o pagamento. Em seguida, clique em **Concluir o pagamento de teste** na página de redirecionamento. |
| Pay by Bank | Seu cliente não faz a autenticação na página de redirecionamento de uma forma de pagamento baseada em redirecionamento e notificação posterior. | Escolha a forma de pagamento, preencha os dados obrigatórios e confirme o pagamento. Em seguida, clique em **Falhar o pagamento de teste** na página de redirecionamento. |
| BLIK | Os pagamentos BLIK falham de várias formas: falhas imediatas (por exemplo, o código está vencido ou inválido), erros atrasados (o banco recusa) ou limites de tempo (o cliente não respondeu a tempo). | Use padrões de e-mail para [simular as diferentes falhas.](https://docs.stripe.com/payments/blik/accept-a-payment.md#simulate-failures) |
#### Débitos bancários
| Forma de pagamento | Cenário | Como testar |
| ---------------------- | ------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Débito automático SEPA | O cliente paga com débito automático SEPA. | Preencha o formulário usando o número de conta `AT321904300235473204`. Inicialmente, o status do PaymentIntent muda para processando e, três minutos depois, para bem-sucedido. |
| Débito automático SEPA | O status da intenção de pagamento do cliente muda de `processing` para `requires_payment_method`. | Preencha o formulário usando o número de conta `AT861904300235473202`. |
#### Boletos
| Forma de pagamento | Cenário | Como testar |
| ------------------ | ------------------------------------------------ | ---------------------------------------------------------------------------------------------- |
| Boleto, OXXO | Seu cliente paga com um boleto ou uma guia OXXO. | Selecione boleto ou OXXO como forma de pagamento e envie o pagamento. Feche o diálogo exibido. |
Consulte [Testes](https://docs.stripe.com/testing.md) para obter mais informações sobre como testar sua integração.
## Optional: Habilitar formas de pagamento adicionais
Navegue para [Gerenciar formas de pagamento para suas contas conectadas](https://dashboard.stripe.com/settings/payment_methods/connected_accounts) no Dashboard para configurar quais formas de pagamento suas contas conectadas aceitam. As alterações nas configurações padrão se aplicam a todas as contas conectadas novas e existentes.
Consulte os seguintes recursos para obter informações sobre formas de pagamento:
- [Um guia de formas de pagamento](https://stripe.com/payments/payment-methods-guide#choosing-the-right-payment-methods-for-your-business) para ajudar você a escolher as formas de pagamento corretas para sua plataforma.
- [Funções da conta](https://docs.stripe.com/connect/account-capabilities.md) para assegurar que as formas de pagamento escolhidas funcionem para suas contas conectadas.
- Tabelas de [suporte a formas de pagamento e produtos](https://docs.stripe.com/payments/payment-methods/payment-method-support.md#product-support) para assegurar que suas formas de pagamento escolhidas funcionem para seus produtos da Stripe e fluxos de pagamento.
Para cada forma de pagamento, você pode selecionar uma das seguintes opções no menu suspenso:
| |
| |
| **Ativadas por padrão** | Suas contas conectadas aceitam esta forma de pagamento durante o checkout. Algumas formas de pagamento podem ser desativadas ou bloqueadas. Isso ocorre porque suas contas conectadas com *acesso ao Stripe Dashboard* (Platforms can provide connected accounts with access to the full Stripe Dashboard or the Express Dashboard. Otherwise, platforms build an interface for connected accounts using embedded components or the Stripe API) precisam ativá-las em sua página de configurações. |
| **Desativadas por padrão** | Suas contas conectadas não aceitam esta forma de pagamento durante o checkout. Se você permitir que contas conectadas com *acessem o Stripe Dashboard* (Platforms can provide connected accounts with access to the full Stripe Dashboard or the Express Dashboard. Otherwise, platforms build an interface for connected accounts using embedded components or the Stripe API) para gerenciar suas próprias formas de pagamento, elas podem ativar esse recurso. |
| **Bloqueadas** | Suas contas conectadas não aceitam esta forma de pagamento durante o checkout. Se você permitir que contas conectadas com *acessem o Stripe Dashboard* (Platforms can provide connected accounts with access to the full Stripe Dashboard or the Express Dashboard. Otherwise, platforms build an interface for connected accounts using embedded components or the Stripe API) para gerenciar suas próprias formas de pagamento, elas não têm a opção para ativar esse recurso. |
Opções de formas de pagamento
Se fizer uma alteração em uma forma de pagamento, você deve clicar em **Revisar alterações** na barra inferior da tela e em **Salvar e aplicar** para atualizar suas contas conectadas.
Salvar diálogo
### Permitir que contas conectadas gerenciem formas de pagamento
A Stripe recomenda permitir que as contas conectadas personalizem suas próprias formas de pagamento. Esta opção permite que cada conta conectada com *acesso ao Stripe Dashboard* (Platforms can provide connected accounts with access to the full Stripe Dashboard or the Express Dashboard. Otherwise, platforms build an interface for connected accounts using embedded components or the Stripe API) para ver e atualizar sua página de [formas de pagamento](https://dashboard.stripe.com/settings/payment_methods). Somente os proprietários das contas conectadas podem personalizar as formas de pagamento. O Stripe Dashboard exibe o conjunto de padrões de forma de pagamento que você aplicou a todas as contas conectadas novas e existentes. Suas contas conectadas podem sobrepor esses padrões, excluindo as formas de pagamento que você bloqueou.
Marque a caixa de seleção **Personalização da conta** para habilitar essa opção. Você deve clicar em **Revisar alterações** na barra inferior da tela e selecionar **Salvar e aplicar** para atualizar essa configuração.
Caixa de seleção de personalização da conta
### Funções das formas de pagamento
Para permitir que suas contas conectadas aceitem formas de pagamento adicionais, suas `Accounts` devem ter recursos de formas de pagamento ativas.
Se você selecionou a opção “On by default” (ativado por padrão) como método de pagamento em[Gerencie formas de pagamento para suas contas conectadas](https://dashboard.stripe.com/settings/payment_methods/connected_accounts), a Stripe solicita automaticamente a funcionalidade necessário para contas conectadas novas e existentes, caso atendam aos requisitos de verificação. Se a conta conectada não atender aos requisitos ou se você quiser ter controle direto, pode solicitação manualmente a funcionalidade no Dashboard ou na API.
A maioria das formas de pagamento possui os mesmos requisitos de verificação que a funcionalidade `card_payments`, com algumas restrições e exceções. A[tabela de formas de pagamento](https://docs.stripe.com/connect/account-capabilities.md#payment-methods) lista os métodos de pagamento que requerem verificação adicional.
#### Dashboard
[Encontre uma conta conectada](https://docs.stripe.com/connect/dashboard/managing-individual-accounts.md#finding-accounts) no Dashboard para editar suas capacidades e visualizar os requisitos de verificação pendentes.
#### API
Para uma conta conectada existente, você pode [listar](https://docs.stripe.com/api/capabilities/list.md) as funções existentes decidir se precisa solicitar funções adicionais.
```curl
curl https://api.stripe.com/v1/accounts/{{CONNECTEDACCOUNT_ID}}/capabilities \
-u "<>:"
```
Solicite funções adicionais [atualizando](https://docs.stripe.com/api/capabilities/update.md) as funções de cada conta conectada.
```curl
curl https://api.stripe.com/v1/accounts/{{CONNECTEDACCOUNT_ID}}/capabilities/us_bank_account_ach_payments \
-u "<>:" \
-d requested=true
```
Pode haver um atraso antes que a função solicitada se torne ativa. Se a função tiver algum requisito de ativação, ele será incluído nas matrizes de `requirements`.
## Coletar tarifas
Como plataforma, você pode cobrar de suas contas conectadas uma parte de cada transação na forma de tarifas da plataforma. Você pode definir a tarifa da plataforma das seguintes maneiras:
- Use a [ferramenta de preços da plataforma](https://docs.stripe.com/connect/platform-pricing-tools.md) para definir e testar regras de preços. No momento, esse recurso no-code no Stripe Dashboard só está disponível para plataformas responsáveis pelo pagamento das tarifas da Stripe.
- Especifique tarifas de aplicação diretamente em um [PaymentIntent](https://docs.stripe.com/api/payment_intents/object.md). As tarifas definidas com esse método substituem a lógica de precificação especificada na Platform Pricing Tool.
Sua plataforma pode cobrar uma tarifa da plataforma com as seguintes limitações:
- O valor de `application_fee_amount` deve ser positivo e inferior ao o valor da cobrança. A tarifa da plataforma recolhida é limitada ao valor capturado da cobrança.
- Não há tarifas adicionais da Stripe sobre a própria tarifa da plataforma.
- Em conformidade com os requisitos regulatórios e de conformidade do Brasil, plataformas sediadas fora do Brasil com contas conectadas brasileiras não podem recolher tarifas da plataforma por meio da Stripe.
- A moeda de `application_fee_amount` depende de alguns fatores de [várias moedas](https://docs.stripe.com/connect/currencies.md).
A [BalanceTransaction](https://docs.stripe.com/api.md#balance_transaction_retrieve) da cobrança resultante inclui um detalhamento das tarifas, tanto da Stripe quanto das tarifas da plataforma. Para proporcionar uma melhor experiência de relatórios, a cobrança de uma tarifa gera um objeto [ApplicationFee](https://docs.stripe.com/api/application_fees/object.md). Use a propriedade `amount`t no objeto `ApplicationFee` para fins de relatório.
Você pode visualizar as tarifas da plataforma na seção [tarifas cobradas](https://dashboard.stripe.com/connect/application_fees) do Dashboard.
> Por padrão, as tarifas da plataforma para cobranças diretas são criadas de forma assíncrona. Se você expandir o objeto `application_fee` em uma solicitação de criação de cobrança, a tarifa da plataforma será criada de forma síncrona como parte dessa solicitação. Somente expanda o objeto `application_fee` se for necessário, pois isso aumenta a latência da solicitação.
>
> Para receber notificações de objetos `ApplicationFee` criados de forma assíncrona, escute o evento de Webhook [application_fee.created](https://docs.stripe.com/api/events/types.md#event_types-application_fee.created).
### Fluxo de fundos com tarifas
Quando você especifica uma tarifa da plataforma em uma cobrança, o valor da tarifa é transferido para a conta Stripe da sua plataforma. Ao processar uma cobrança diretamente na conta conectada, o valor da cobrança — menos a tarifa da Stripe e tarifa da plataforma — é depositado na conta conectada.
Por exemplo, se você fizer uma cobrança de 10 USD com uma tarifa da plataforma de 1,23 USD (como no exemplo anterior), 1,23 USD serão transferidos para a conta da sua plataforma. 8,18 USD (10 USD - 0,59 USD - 1,23 USD) serão liquidados na conta conectada (assumindo as tarifas padrão da Stripe nos EUA).
Se você processa pagamentos em várias moedas, veja [como as moedas são gerenciadas](https://docs.stripe.com/connect/currencies.md) no Connect.
## Personalizar a marca
Sua plataforma e suas contas conectadas podem usar as [Configurações de marca](https://dashboard.stripe.com/account/branding) no Dashboard para personalizar as marcas na página de pagamentos. Para cobranças diretas, o Checkout usa as configurações de marca da conta conectada.
Você também pode usar a API para [atualizar configurações de marca](https://docs.stripe.com/api/accounts/update.md#update_account-settings-branding):
- `icon` - Exibido próximo ao nome da empresa, no cabeçalho da página de Checkout.
- `logo` - É exibido no lugar do ícone e do nome da empresa, no cabeçalho da página de Checkout.
- `primary_color` - Cor de fundo da página de Checkout.
- `secondary_color` - Cor dos botões da página de Checkout.
```curl
curl https://api.stripe.com/v1/accounts/{{CONNECTEDACCOUNT_ID}} \
-u "<>:" \
-d "settings[branding][icon]"="{{FILE_ID}}" \
-d "settings[branding][logo]"="{{FILE_ID}}" \
--data-urlencode "settings[branding][primary_color]"="#663399" \
--data-urlencode "settings[branding][secondary_color]"="#4BB543"
```
Incorpore um formulário de pagamento pré-integrado ao seu site usando o [Stripe Checkout](https://docs.stripe.com/payments/checkout.md). [Compare esta integração com as outras formas de integração da Stripe](https://docs.stripe.com/payments/online-payments.md#compare-features-and-availability).
#### Esforço de integração
Complexity: 2/5
#### Tipo de integração
Integrar um formulário de pagamento pré-configurado ao seu site
#### Personalização da IU
Personalização limitada
- 20 fontes predefinidas
- 3 raios de borda predefinidos
- Cores do fundo e das bordas personalizadas
- Logotipo personalizado
Primeiro, [cadastre-se](https://dashboard.stripe.com/register) para obter uma conta Stripe.
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 uma sessão do Checkout [Lado do servidor]
Uma [Sessão do Checkout](https://docs.stripe.com/api/checkout/sessions.md) controla o que o seu cliente vê no formulário de pagamento integrável, como itens de linha, o valor do pedido e a moeda. Crie uma sessão do Checkout em um endpoint no lado do servidor (por exemplo, `/create-checkout-session`). A resposta inclui um `client_secret` que você usará na próxima etapa para montar o Checkout.
```curl
curl https://api.stripe.com/v1/checkout/sessions \
-u "<>:" \
-H "Stripe-Account: {{CONNECTEDACCOUNT_ID}}" \
-d "line_items[0][price_data][currency]"=usd \
-d "line_items[0][price_data][product_data][name]"=T-shirt \
-d "line_items[0][price_data][unit_amount]"=1000 \
-d "line_items[0][quantity]"=1 \
-d "payment_intent_data[application_fee_amount]"=123 \
-d mode=payment \
-d ui_mode=embedded \
--data-urlencode return_url="https://example.com/checkout/return?session_id={CHECKOUT_SESSION_ID}"
```
- `Stripe-Account`: este cabeçalho indica uma cobrança direta para sua conta conectada. A [marca](https://docs.stripe.com/connect/direct-charges.md#branding) da conta conectada é usada no Checkout, o que permite que os clientes tenham a sensação de interagir diretamente com a conta conectada em vez de com sua plataforma.
- `line_items`: este atributo representa os itens que seu cliente está comprando e é exibido no formulário de pagamento integrado.
- `payment_intent_data[application_fee_amount]`: este atributo especifica o valor que sua plataforma deduz da transação como tarifa da plataforma. Depois que o pagamento é processado na conta conectada, o `application_fee_amount` é transferido para a plataforma. Consulte [coletar tarifas](https://docs.stripe.com/connect/direct-charges.md#collect-fees) para obter mais informações.
- `return_url`: a Stripe redireciona o cliente para a URL de retorno depois que ele conclui uma tentativa de pagamento e substitui a string `{CHECKOUT_SESSION_ID}` pelo ID da sessão de checkout. Use isso para recuperar a sessão de checkout e inspecionar o status para decidir o que mostrar ao cliente. Certifique-se de que a URL de retorno corresponda a uma página em seu site que forneça o status do pagamento. Você também pode anexar seus próprios parâmetros de consulta, que persistem durante o processo de redirecionamento. Consulte [como personalizar o comportamento de redirecionamento com um formulário incorporado](https://docs.stripe.com/payments/checkout/custom-success-page.md?payment-ui=embedded-form) para obter mais informações.
As cobranças que você cria diretamente na conta conectada são relatados apenas nessa conta e [em seu Dashboard do Connect](https://docs.stripe.com/connect/dashboard/understand-your-connect-business.md#supported-charges). Para consultar elementos de transação como `PaymentIntents` e `Charges` para cobranças diretas, você deve consultar a Stripe API [usando a ID da conta conectada no cabeçalho Stripe-Account](https://docs.stripe.com/connect/authentication.md).
## Montar Checkout [Lado do cliente]
#### HTML + JS
O Checkout está disponível como parte do [Stripe.js](https://docs.stripe.com/js.md). Inclua o script do Stripe.js na sua página, adicionando-o ao cabeçalho do arquivo HTML. Em seguida, crie um nó DOM vazio (contêiner) para usar na montagem.
```html
```
Inicialize o Stripe.js com sua chave de API publicável e o ID da conta conectada. Passe o `client_secret` da etapa anterior para `options` quando criar a instância do Checkout:
```javascript
// Initialize Stripe.js
const stripe = Stripe('<>', {
stripeAccount: '{{CONNECTED_ACCOUNT_ID}}',
});
initialize();
// Fetch Checkout Session and retrieve the client secret
async function initialize() {
const fetchClientSecret = async () => {
const response = await fetch("/create-checkout-session", {
method: "POST",
});
const { clientSecret } = await response.json();
return clientSecret;
};
// Initialize Checkout
const checkout = await stripe.initEmbeddedCheckout({
fetchClientSecret,
});
// Mount Checkout
checkout.mount('#checkout');
}
```
#### 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 npm:
```bash
npm install --save @stripe/react-stripe-js @stripe/stripe-js
```
Para usar o componente Embedded Checkout, crie um `EmbeddedCheckoutProvider`. Chame `loadStripe` com sua chave de API publicável e passe `Promise` retornada para o provedor. Use as `options` aceitas pelo provedor para passar o `client_secret` da etapa anterior.
```jsx
import * as React from 'react';
import {loadStripe} from '@stripe/stripe-js';
import {
EmbeddedCheckoutProvider,
EmbeddedCheckout
} from '@stripe/react-stripe-js';
// Make sure to call `loadStripe` outside of a component's render to avoid
// recreating the `Stripe` object on every render.
const stripePromise = loadStripe('<>', {
stripeAccount: '{{CONNECTED_ACCOUNT_ID}}',
});
const App = ({clientSecret}) => {
const options = {clientSecret};
return (
)
}
```
O Checkout é renderizado em um iframe que envia dados de pagamento com segurança à Stripe por uma conexão HTTPS. Evite colocar o Checkout dentro de outro iframe porque algumas formas de pagamento exigem o redirecionamento para outra página para confirmação do pagamento.
## Gerenciar eventos pós-pagamento [Lado do servidor]
A Stripe envia um evento [checkout.session.completed](https://docs.stripe.com/api/events/types.md#event_types-checkout.session.completed) quando o pagamento é concluído. [Use um webhook para receber esses eventos](https://docs.stripe.com/webhooks/quickstart.md) 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 poderia fechar a janela do navegador ou sair do aplicativo antes da execução do retorno de chamada. Algumas formas de pagamento também demoram de 2 a 14 dias para a confirmação do pagamento. Configurar sua integração para escutar eventos assíncronos é o que permite a você aceitar diferentes tipos de [formas de pagamento](https://stripe.com/payments/payment-methods-guide) com uma única integração.
A Stripe recomenda gerenciar todos os eventos a seguir ao receber pagamentos com o Checkout:
| Evento | Descrição | Próximas etapas |
| -------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------ | ------------------------------------------------------------------------------------ |
| [checkout.session.completed](https://docs.stripe.com/api/events/types.md#event_types-checkout.session.completed) | O cliente autorizou o pagamento enviando o formulário do Checkout. | Aguarde a confirmação ou falha do pagamento. |
| [checkout.session.async_payment_succeeded](https://docs.stripe.com/api/events/types.md#event_types-checkout.session.async_payment_succeeded) | O pagamento do cliente foi confirmado. | Execute o pedido de mercadorias ou serviços. |
| [checkout.session.async_payment_failed](https://docs.stripe.com/api/events/types.md#event_types-checkout.session.async_payment_failed) | O pagamento foi recusado ou houve outro erro. | Entre em contato com o cliente por e-mail e solicite a realização de um novo pedido. |
Todos esses eventos incluem o objeto [Checkout Session](https://docs.stripe.com/api/checkout/sessions.md). Após o pagamento, o [status](https://docs.stripe.com/payments/paymentintents/lifecycle.md) subjacente do *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) muda de `processing` para `succeeded` ou um status malsucedido.
## Testar a integração
#### Cartões
| Número do cartão | Cenário | Como testar |
| ------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------- |
| 4242424242424242 | O pagamento com cartão é bem-sucedido e não precisa de autenticação. | Preencha o formulário do cartão de crédito usando o número do cartão de crédito com qualquer validade, CVC e código postal. |
| 4000002500003155 | O pagamento com cartão precisa de *autenticação* (Strong Customer Authentication (SCA) is a regulatory requirement in effect as of September 14, 2019, that impacts many European online payments. It requires customers to use two-factor authentication like 3D Secure to verify their purchase). | Preencha o formulário do cartão de crédito usando o número do cartão de crédito com qualquer validade, CVC e código postal. |
| 4000000000009995 | O cartão é recusado com um código de recusa como `insufficient_funds`. | Preencha o formulário do cartão de crédito usando o número do cartão de crédito com qualquer validade, CVC e código postal. |
| 6205500000000000004 | O cartão UnionPay tem um comprimento variável de 13 a 19 dígitos. | Preencha o formulário do cartão de crédito usando o número do cartão de crédito com qualquer validade, CVC e código postal. |
#### Carteiras
| Forma de pagamento | Cenário | Como testar |
| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Alipay | O cliente paga com uma forma de pagamento baseada em redirecionamento e [notificação imediata](https://docs.stripe.com/payments/payment-methods.md#payment-notification). | Escolha qualquer forma de pagamento baseada em redirecionamento, preencha os dados obrigatórios e confirme o pagamento. Em seguida, clique em **Concluir o pagamento de teste** na página de redirecionamento. |
#### Débito bancário autenticado
| Forma de pagamento | Cenário | Como testar |
| ------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Débito automático BECS | O cliente paga com débito automático BECS. | Preencha o formulário usando o número de conta `900123456` e BSB `000000`. Inicialmente, o status do PaymentIntent muda para `processing` e, 3 minutos depois, para `succeeded`. |
| Débito automático BECS | O pagamento do cliente falha com um código de erro `account_closed`. | Preencha o formulário usando o número da conta `111111113` e BSB `000000`. |
| Bancontact, EPS, iDEAL, e Przelewy24 | Seu cliente não faz a autenticação na página de redirecionamento de uma forma de pagamento baseada em redirecionamento e notificação imediata. | Escolha qualquer forma de pagamento baseada em redirecionamento, preencha os dados obrigatórios e confirme o pagamento. Em seguida, clique em **Falhar pagamento de teste** na página de redirecionamento. |
| Pay by Bank | O cliente paga com uma forma de pagamento baseada em redirecionamento e [notificação posterior](https://docs.stripe.com/payments/payment-methods.md#payment-notification). | Escolha a forma de pagamento, preencha os dados obrigatórios e confirme o pagamento. Em seguida, clique em **Concluir o pagamento de teste** na página de redirecionamento. |
| Pay by Bank | Seu cliente não faz a autenticação na página de redirecionamento de uma forma de pagamento baseada em redirecionamento e notificação posterior. | Escolha a forma de pagamento, preencha os dados obrigatórios e confirme o pagamento. Em seguida, clique em **Falhar o pagamento de teste** na página de redirecionamento. |
| BLIK | Os pagamentos BLIK falham de várias formas: falhas imediatas (por exemplo, o código está vencido ou inválido), erros atrasados (o banco recusa) ou limites de tempo (o cliente não respondeu a tempo). | Use padrões de e-mail para [simular as diferentes falhas.](https://docs.stripe.com/payments/blik/accept-a-payment.md#simulate-failures) |
#### Débitos bancários
| Forma de pagamento | Cenário | Como testar |
| ---------------------- | ------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Débito automático SEPA | O cliente paga com débito automático SEPA. | Preencha o formulário usando o número de conta `AT321904300235473204`. Inicialmente, o status do PaymentIntent muda para processando e, três minutos depois, para bem-sucedido. |
| Débito automático SEPA | O status da intenção de pagamento do cliente muda de `processing` para `requires_payment_method`. | Preencha o formulário usando o número de conta `AT861904300235473202`. |
#### Boletos
| Forma de pagamento | Cenário | Como testar |
| ------------------ | ------------------------------------------------ | ---------------------------------------------------------------------------------------------- |
| Boleto, OXXO | Seu cliente paga com um boleto ou uma guia OXXO. | Selecione boleto ou OXXO como forma de pagamento e envie o pagamento. Feche o diálogo exibido. |
Consulte [Testes](https://docs.stripe.com/testing.md) para obter mais informações sobre como testar sua integração.
## Optional: Habilitar formas de pagamento adicionais
Navegue para [Gerenciar formas de pagamento para suas contas conectadas](https://dashboard.stripe.com/settings/payment_methods/connected_accounts) no Dashboard para configurar quais formas de pagamento suas contas conectadas aceitam. As alterações nas configurações padrão se aplicam a todas as contas conectadas novas e existentes.
Consulte os seguintes recursos para obter informações sobre formas de pagamento:
- [Um guia de formas de pagamento](https://stripe.com/payments/payment-methods-guide#choosing-the-right-payment-methods-for-your-business) para ajudar você a escolher as formas de pagamento corretas para sua plataforma.
- [Funções da conta](https://docs.stripe.com/connect/account-capabilities.md) para assegurar que as formas de pagamento escolhidas funcionem para suas contas conectadas.
- Tabelas de [suporte a formas de pagamento e produtos](https://docs.stripe.com/payments/payment-methods/payment-method-support.md#product-support) para assegurar que suas formas de pagamento escolhidas funcionem para seus produtos da Stripe e fluxos de pagamento.
Para cada forma de pagamento, você pode selecionar uma das seguintes opções no menu suspenso:
| |
| |
| **Ativadas por padrão** | Suas contas conectadas aceitam esta forma de pagamento durante o checkout. Algumas formas de pagamento podem ser desativadas ou bloqueadas. Isso ocorre porque suas contas conectadas com *acesso ao Stripe Dashboard* (Platforms can provide connected accounts with access to the full Stripe Dashboard or the Express Dashboard. Otherwise, platforms build an interface for connected accounts using embedded components or the Stripe API) precisam ativá-las em sua página de configurações. |
| **Desativadas por padrão** | Suas contas conectadas não aceitam esta forma de pagamento durante o checkout. Se você permitir que contas conectadas com *acessem o Stripe Dashboard* (Platforms can provide connected accounts with access to the full Stripe Dashboard or the Express Dashboard. Otherwise, platforms build an interface for connected accounts using embedded components or the Stripe API) para gerenciar suas próprias formas de pagamento, elas podem ativar esse recurso. |
| **Bloqueadas** | Suas contas conectadas não aceitam esta forma de pagamento durante o checkout. Se você permitir que contas conectadas com *acessem o Stripe Dashboard* (Platforms can provide connected accounts with access to the full Stripe Dashboard or the Express Dashboard. Otherwise, platforms build an interface for connected accounts using embedded components or the Stripe API) para gerenciar suas próprias formas de pagamento, elas não têm a opção para ativar esse recurso. |
Opções de formas de pagamento
Se fizer uma alteração em uma forma de pagamento, você deve clicar em **Revisar alterações** na barra inferior da tela e em **Salvar e aplicar** para atualizar suas contas conectadas.
Salvar diálogo
### Permitir que contas conectadas gerenciem formas de pagamento
A Stripe recomenda permitir que as contas conectadas personalizem suas próprias formas de pagamento. Esta opção permite que cada conta conectada com *acesso ao Stripe Dashboard* (Platforms can provide connected accounts with access to the full Stripe Dashboard or the Express Dashboard. Otherwise, platforms build an interface for connected accounts using embedded components or the Stripe API) para ver e atualizar sua página de [formas de pagamento](https://dashboard.stripe.com/settings/payment_methods). Somente os proprietários das contas conectadas podem personalizar as formas de pagamento. O Stripe Dashboard exibe o conjunto de padrões de forma de pagamento que você aplicou a todas as contas conectadas novas e existentes. Suas contas conectadas podem sobrepor esses padrões, excluindo as formas de pagamento que você bloqueou.
Marque a caixa de seleção **Personalização da conta** para habilitar essa opção. Você deve clicar em **Revisar alterações** na barra inferior da tela e selecionar **Salvar e aplicar** para atualizar essa configuração.
Caixa de seleção de personalização da conta
### Funções das formas de pagamento
Para permitir que suas contas conectadas aceitem formas de pagamento adicionais, suas `Accounts` devem ter recursos de formas de pagamento ativas.
Se você selecionou a opção “On by default” (ativado por padrão) como método de pagamento em[Gerencie formas de pagamento para suas contas conectadas](https://dashboard.stripe.com/settings/payment_methods/connected_accounts), a Stripe solicita automaticamente a funcionalidade necessário para contas conectadas novas e existentes, caso atendam aos requisitos de verificação. Se a conta conectada não atender aos requisitos ou se você quiser ter controle direto, pode solicitação manualmente a funcionalidade no Dashboard ou na API.
A maioria das formas de pagamento possui os mesmos requisitos de verificação que a funcionalidade `card_payments`, com algumas restrições e exceções. A[tabela de formas de pagamento](https://docs.stripe.com/connect/account-capabilities.md#payment-methods) lista os métodos de pagamento que requerem verificação adicional.
#### Dashboard
[Encontre uma conta conectada](https://docs.stripe.com/connect/dashboard/managing-individual-accounts.md#finding-accounts) no Dashboard para editar suas capacidades e visualizar os requisitos de verificação pendentes.
#### API
Para uma conta conectada existente, você pode [listar](https://docs.stripe.com/api/capabilities/list.md) as funções existentes decidir se precisa solicitar funções adicionais.
```curl
curl https://api.stripe.com/v1/accounts/{{CONNECTEDACCOUNT_ID}}/capabilities \
-u "<>:"
```
Solicite funções adicionais [atualizando](https://docs.stripe.com/api/capabilities/update.md) as funções de cada conta conectada.
```curl
curl https://api.stripe.com/v1/accounts/{{CONNECTEDACCOUNT_ID}}/capabilities/us_bank_account_ach_payments \
-u "<>:" \
-d requested=true
```
Pode haver um atraso antes que a função solicitada se torne ativa. Se a função tiver algum requisito de ativação, ele será incluído nas matrizes de `requirements`.
## Coletar tarifas
Como plataforma, você pode cobrar de suas contas conectadas uma parte de cada transação na forma de tarifas da plataforma. Você pode definir a tarifa da plataforma das seguintes maneiras:
- Use a [ferramenta de preços da plataforma](https://docs.stripe.com/connect/platform-pricing-tools.md) para definir e testar regras de preços. No momento, esse recurso no-code no Stripe Dashboard só está disponível para plataformas responsáveis pelo pagamento das tarifas da Stripe.
- Especifique tarifas de aplicação diretamente em um [PaymentIntent](https://docs.stripe.com/api/payment_intents/object.md). As tarifas definidas com esse método substituem a lógica de precificação especificada na Platform Pricing Tool.
Sua plataforma pode cobrar uma tarifa da plataforma com as seguintes limitações:
- O valor de `application_fee_amount` deve ser positivo e inferior ao o valor da cobrança. A tarifa da plataforma recolhida é limitada ao valor capturado da cobrança.
- Não há tarifas adicionais da Stripe sobre a própria tarifa da plataforma.
- Em conformidade com os requisitos regulatórios e de conformidade do Brasil, plataformas sediadas fora do Brasil com contas conectadas brasileiras não podem recolher tarifas da plataforma por meio da Stripe.
- A moeda de `application_fee_amount` depende de alguns fatores de [várias moedas](https://docs.stripe.com/connect/currencies.md).
A [BalanceTransaction](https://docs.stripe.com/api.md#balance_transaction_retrieve) da cobrança resultante inclui um detalhamento das tarifas, tanto da Stripe quanto das tarifas da plataforma. Para proporcionar uma melhor experiência de relatórios, a cobrança de uma tarifa gera um objeto [ApplicationFee](https://docs.stripe.com/api/application_fees/object.md). Use a propriedade `amount`t no objeto `ApplicationFee` para fins de relatório.
Você pode visualizar as tarifas da plataforma na seção [tarifas cobradas](https://dashboard.stripe.com/connect/application_fees) do Dashboard.
> Por padrão, as tarifas da plataforma para cobranças diretas são criadas de forma assíncrona. Se você expandir o objeto `application_fee` em uma solicitação de criação de cobrança, a tarifa da plataforma será criada de forma síncrona como parte dessa solicitação. Somente expanda o objeto `application_fee` se for necessário, pois isso aumenta a latência da solicitação.
>
> Para receber notificações de objetos `ApplicationFee` criados de forma assíncrona, escute o evento de Webhook [application_fee.created](https://docs.stripe.com/api/events/types.md#event_types-application_fee.created).
## Personalizar a marca
Sua plataforma e suas contas conectadas podem usar as [Configurações de marca](https://dashboard.stripe.com/account/branding) no Dashboard para personalizar as marcas na página de pagamentos. Para cobranças diretas, o Checkout usa as configurações de marca da conta conectada.
Você também pode usar a API para [atualizar configurações de marca](https://docs.stripe.com/api/accounts/update.md#update_account-settings-branding):
- `icon` - Exibido próximo ao nome da empresa, no cabeçalho da página de Checkout.
- `logo` - É exibido no lugar do ícone e do nome da empresa, no cabeçalho da página de Checkout.
- `primary_color` - Cor de fundo da página de Checkout.
- `secondary_color` - Cor dos botões da página de Checkout.
```curl
curl https://api.stripe.com/v1/accounts/{{CONNECTEDACCOUNT_ID}} \
-u "<>:" \
-d "settings[branding][icon]"="{{FILE_ID}}" \
-d "settings[branding][logo]"="{{FILE_ID}}" \
--data-urlencode "settings[branding][primary_color]"="#663399" \
--data-urlencode "settings[branding][secondary_color]"="#4BB543"
```
Crie uma integração de pagamentos personalizada incorporando componentes de IU ao seu site usando o [Stripe Elements](https://docs.stripe.com/payments/elements.md). O código no lado do cliente e do servidor cria um formulário de checkout que aceita várias formas de pagamento. [Compare esta integração com as outras formas de integração da Stripe](https://docs.stripe.com/payments/online-payments.md#compare-features-and-availability).
#### Esforço de integração
Complexity: 3/5
#### Tipo de integração
Combine componentes de IU em um fluxo de pagamento personalizado
#### Personalização da IU
Personalização no nível de CSS com a [API Appearance](https://docs.stripe.com/elements/appearance-api.md)
Primeiro, [cadastre-se](https://dashboard.stripe.com/register) para obter uma conta Stripe.
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 suas tentativas de cobrança e alterações no estado do pagamento durante todo o processo.
Uma visão geral resumida da integração de pagamentos descrita neste documento. (See full diagram at https://docs.stripe.com/connect/direct-charges)
As formas de pagamento mostradas aos clientes durante o processo de checkout também estão incluídas no PaymentIntent. Você pode deixar que a Stripe obtenha automaticamente as formas de pagamento das configurações do Dashboard ou listá-las manualmente.
A menos que sua integração exija uma opção baseada em código para oferecer formas de pagamento, não liste as formas de pagamento manualmente. A Stripe avalia as restrições de moeda, forma de pagamento e outros parâmetros para determinar a lista de formas de pagamento aceitas. A Stripe prioriza as formas de pagamento que ajudam a aumentar a conversão e são mais relevantes para a moeda e a localização do cliente. A Stripe oculta as formas de pagamento de prioridade menor em um menu de navegação.
#### Gerenciar formas de pagamento no Dashboard
Crie um PaymentIntent no seu servidor com um valor e uma moeda. Na versão mais recente da API, especificar o parâmetro `automatic_payment_methods` é opcional porque a Stripe habilita sua funcionalidade por padrão. Você pode gerenciar formas de pagamento no [Dashboard](https://dashboard.stripe.com/settings/payment_methods). A Stripe processa a devolução de formas de pagamento qualificadas com base em fatores como valor, moeda e fluxo de pagamento da transação.
```curl
curl https://api.stripe.com/v1/payment_intents \
-u "<>:" \
-H "Stripe-Account: {{CONNECTEDACCOUNT_ID}}" \
-d amount=1000 \
-d currency=usd \
-d "automatic_payment_methods[enabled]"=true \
-d application_fee_amount=123
```
#### Listar manualmente as formas de pagamento
```curl
curl https://api.stripe.com/v1/payment_intents \
-u "<>:" \
-H "Stripe-Account: {{CONNECTEDACCOUNT_ID}}" \
-d amount=1099 \
-d currency=eur \
-d "payment_method_types[]"=bancontact \
-d "payment_method_types[]"=card \
-d "payment_method_types[]"=eps \
-d "payment_method_types[]"=ideal \
-d "payment_method_types[]"=p24 \
-d "payment_method_types[]"=sepa_debit \
-d "payment_method_types[]"=sofort \
-d application_fee_amount=123
```
Ao criar um PaymentIntent, você precisa especificar certos parâmetros:
- `amount` - crie um PaymentIntent no seu servidor com um valor especificado. Sempre determine o valor a ser cobrado no lado do servidor, pois esse é um ambiente confiável. Essa abordagem evita que clientes mal-intencionados escolham seus próprios preços.
- `currency` - a moeda incluída no PaymentIntent filtra as formas de pagamento mostradas ao cliente. Portanto, escolha-a de acordo com as formas de pagamento que deseja oferecer. Por exemplo, se você passar `eur` e a OXXO estiver ativada no Dashboard, a OXXO não aparecerá para o cliente porque não aceita pagamentos em `eur`. Algumas formas de pagamento aceitam várias moedas e países. Este guia usa Bancontact, cartões de crédito, EPS, iDEAL, Przelewy24, débito automático SEPA e Sofort nos exemplos de código.
- `"payment_method_types[]"` - liste manualmente todas as formas de pagamento que deseja aceitar.
- (Opcional) `payment_intent_data[application_fee_amount]` - este argumento especifica o valor que sua plataforma planeja obter da transação. Se estiver usando a [ferramenta de preços da plataforma](https://docs.stripe.com/connect/platform-pricing-tools.md) da Stripe para gerenciar preços de tarifas da plataforma no [Dashboard](https://dashboard.stripe.com/test/settings/connect/platform_pricing/payments), não inclua este argumento, pois ele substituirá qualquer lógica de preços definida pela ferramenta. Após o processamento do pagamento na conta conectada, o `application_fee_amount` é transferido para a plataforma, e a tarifa da Stripe é deduzida do saldo da conta conectada.
> A forma de pagamento precisa aceitar a moeda passada no PaymentIntent. Além disso, sua empresa precisa estar estabelecida em um dos países aceitos pela forma de pagamento. Consulte [Opções de integração de formas de pagamento](https://docs.stripe.com/payments/payment-methods/integration-options.md) para obter mais detalhes sobre o que é aceito.
### Recuperar o segredo do cliente
O 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)) que o lado do cliente usa para concluir com segurança o processo de pagamento. Você pode usar abordagens diferentes para enviar a senha do cliente ao lado do cliente.
#### Aplicativo de página única
Recupere o segredo do cliente de um endpoint do servidor usando a função `fetch` do navegador. Essa abordagem é melhor quando o lado do cliente é um aplicativo com uma única página, principalmente se criado com uma estrutura de front-end moderna como o React. Crie o endpoint do servidor que envia o segredo do cliente:
#### Ruby
```ruby
get '/secret' do
intent = # ... Create or retrieve the PaymentIntent
{client_secret: intent.client_secret}.to_json
end
```
Em seguida, obtenha o segredo do cliente com JavaScript no lado do cliente:
```javascript
(async () => {
const response = await fetch('/secret');
const {client_secret: clientSecret} = await response.json();
// Render the form using the clientSecret
})();
```
#### Renderização do lado do servidor
Passe o segredo do cliente do servidor ao cliente. Essa abordagem funciona melhor quando o aplicativo gera conteúdo estático no servidor antes de enviá-lo ao navegador.
Adicione o [client_secret](https://docs.stripe.com/api/payment_intents/object.md#payment_intent_object-client_secret) ao formulário de checkout. No código do lado do servidor, recupere o segredo do cliente do PaymentIntent:
#### Ruby
```erb
```
```ruby
get '/checkout' do
@intent = # ... Fetch or create the PaymentIntent
erb :checkout
end
```
## 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 uma ampla variedade de 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 precisa ter o atributo [permitir](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/iframe#attr-allowpaymentrequest) definido como `"payment *"` igual.
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 o 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
Checkout
```
Crie uma instância da `Stripe` com o seguinte JavaScript na página de checkout:
```javascript
// Initialize Stripe.js with the same connected account ID used when creating
// the PaymentIntent.
const stripe = Stripe('<>', {
stripeAccount: '{{CONNECTED_ACCOUNT_ID}}'
});
```
### Adicionar o Stripe Elements e o Payment Element à página de pagamentos
O Payment Element precisa de um lugar para residir na sua página de pagamentos. Crie um node DOM vazio (contêiner) com um ID único no seu formulário de pagamento.
```html
```
Quando o formulário tiver sido carregado, crie uma instância do Payment Element e monte-o no node DOM do contêiner com o [segredo do cliente](https://docs.stripe.com/api/payment_intents/object.md#payment_intent_object-client_secret) da etapa anterior. Passe esse valor como uma opção quando criar a instância do [Elements](https://docs.stripe.com/js/elements_object/create).
O segredo do cliente precisa ser administrado com cuidado, porque pode finalizar a cobrança. Não armazene, insira em URL nem exponha o segredo para ninguém, exceto para o próprio cliente.
```javascript
const options = {
clientSecret: '{{CLIENT_SECRET}}',
// Fully customizable with the Appearance API
appearance: {/*...*/},
};
// Set up Stripe.js and Elements to use in checkout form using the client secret
const elements = stripe.elements(options);
// Create and mount the Payment Element
const paymentElement = elements.create("payment");
paymentElement.mount("#payment-element");
```
O Payment Element renderiza um formulário dinâmico, onde o cliente escolhe uma forma de pagamento. O formulário coleta automaticamente todos os dados de pagamento necessários para a forma de pagamento selecionada pelo cliente. Durante a configuração do objeto `Elements`, você pode [personalizar a aparência do Payment Element](https://docs.stripe.com/elements/appearance-api.md) de acordo com o design do site.
#### React
### Configurar o 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
```
### Adicionar e configurar o provedor do Elements à sua página de pagamento
Para usar o componente Payment Element, insira 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 e o [segredo do cliente](https://docs.stripe.com/api/payment_intents/object.md#payment_intent_object-client_secret) da etapa anterior como `options` no provedor do `Elements`.
```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("<>", {
stripeAccount: '{{CONNECTED_ACCOUNT_ID}}'
});
function App() {
const options = {
// pass the client secret from the previous step
clientSecret: '{{CLIENT_SECRET}}',
// Fully customizable with the Appearance API
appearance: {/*...*/},
};
return (
);
};
ReactDOM.render(, document.getElementById('root'));
```
### Adicionar o componente PaymentElement
Use o componente `PaymentElement` para criar seu formulário.
```jsx
import React from 'react';
import {PaymentElement} from '@stripe/react-stripe-js';
const CheckoutForm = () => {
return (
);
};
export default CheckoutForm;
```
O Payment Element renderiza um formulário dinâmico, onde o cliente escolhe um tipo de forma de pagamento. O formulário coleta automaticamente todos os dados de pagamento necessários para a forma de pagamento selecionada pelo cliente. Durante a configuração do provedor do `Elements`, você pode [personalizar a aparência do Payment Element](https://docs.stripe.com/elements/appearance-api.md) de acordo com o design do site.
## 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 utilizando 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 deve redirecionar o usuário após a conclusão do pagamento. Seu usuário pode ser redirecionado primeiro para um site intermediário, como uma página de autorização bancária, antes de ser redirecionado para o `return_url`. Os pagamentos com cartão são redirecionados imediatamente para o `return_url` quando um pagamento é finalizado.
Se não quiser redirecionar pagamentos com cartão após a conclusão do pagamento, defina [redirecionar](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');
form.addEventListener('submit', async (event) => {
event.preventDefault();
const {error} = await stripe.confirmPayment({
//`Elements` instance that was used to create the Payment Element
elements,
confirmParams: {
return_url: 'https://example.com/order/123/complete',
},
});
if (error) {
// This point will only be reached if there is an immediate error when
// confirming the payment. Show error to your customer (for example, payment
// details incomplete)
const messageContainer = document.querySelector('#error-message');
messageContainer.textContent = error.message;
} else {
// Your customer will be redirected to your `return_url`. For some payment
// methods like iDEAL, your customer will be redirected to an intermediate
// site first to authorize the payment, then redirected to the `return_url`.
}
});
```
#### React
Para chamar [stripe.confirmPayment](https://docs.stripe.com/js/payment_intents/confirm_payment) do seu componente de formulário de pagamento, use os hooks [useStripe](https://docs.stripe.com/sdks/stripejs-react.md#usestripe-hook) e [useElements](https://docs.stripe.com/sdks/stripejs-react.md#useelements-hook).
Se preferir componentes de classe tradicionais em vez de hooks, use um [ElementsConsumer](https://docs.stripe.com/sdks/stripejs-react.md#elements-consumer).
```jsx
import React, {useState} from 'react';
import {useStripe, useElements, PaymentElement} from '@stripe/react-stripe-js';
const CheckoutForm = () => {
const stripe = useStripe();
const elements = useElements();
const [errorMessage, setErrorMessage] = useState(null);
const handleSubmit = async (event) => {
// We don't want to let default form submission happen here,
// which would refresh the page.
event.preventDefault();
if (!stripe || !elements) {
// Stripe.js hasn't yet loaded.
// Make sure to disable form submission until Stripe.js has loaded.
return;
}
const {error} = await stripe.confirmPayment({
//`Elements` instance that was used to create the Payment Element
elements,
confirmParams: {
return_url: 'https://example.com/order/123/complete',
},
});
if (error) {
// This point will only be reached if there is an immediate error when
// confirming the payment. Show error to your customer (for example, payment
// details incomplete)
setErrorMessage(error.message);
} else {
// Your customer will be redirected to your `return_url`. For some payment
// methods like iDEAL, your customer will be redirected to an intermediate
// site first to authorize the payment, then redirected to the `return_url`.
}
};
return (
);
};
export default CheckoutForm;
```
Verifique se o `return_url` corresponde a uma página no seu site que fornece o status do pagamento. Quando a Stripe redireciona o cliente para o `return_url`, nós fornecemos os seguintes parâmetros de consulta de URL:
| Parâmetro | Descrição |
| ------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------- |
| `payment_intent` | O identificador único do `PaymentIntent`. |
| `payment_intent_client_secret` | O [segredo do cliente](https://docs.stripe.com/api/payment_intents/object.md#payment_intent_object-client_secret) do objeto `PaymentIntent`. |
> Se você tiver ferramentas que rastreiam a sessão do cliente no navegador, pode ser necessário adicionar o domínio `stripe.com` à lista de exclusão de referenciadores. Os redirecionamentos fazem com que algumas ferramentas criem novas sessões, o que impede que você rastreie a sessão completa.
Use um dos parâmetros de consulta para recuperar o PaymentIntent. Inspecione o [status do PaymentIntent](https://docs.stripe.com/payments/paymentintents/lifecycle.md) para decidir o que mostrar aos clientes. Você também pode anexar seus próprios parâmetros de consulta ao fornecer o `return_url`, que persiste durante o processo de redirecionamento.
#### HTML + JS
```javascript
// Initialize Stripe.js using your publishable key
const stripe = Stripe('<>');
// Retrieve the "payment_intent_client_secret" query parameter appended to
// your return_url by Stripe.js
const clientSecret = new URLSearchParams(window.location.search).get(
'payment_intent_client_secret'
);
// Retrieve the PaymentIntent
stripe.retrievePaymentIntent(clientSecret).then(({paymentIntent}) => {
const message = document.querySelector('#message')
// Inspect the PaymentIntent `status` to indicate the status of the payment
// to your customer.
//
// Some payment methods will [immediately succeed or fail][0] upon
// confirmation, while others will first enter a `processing` state.
//
// [0]: https://stripe.com/docs/payments/payment-methods#payment-notification
switch (paymentIntent.status) {
case 'succeeded':
message.innerText = 'Success! Payment received.';
break;
case 'processing':
message.innerText = "Payment processing. We'll update you when payment is received.";
break;
case 'requires_payment_method':
message.innerText = 'Payment failed. Please try another payment method.';
// Redirect your user back to your payment page to attempt collecting
// payment again
break;
default:
message.innerText = 'Something went wrong.';
break;
}
});
```
#### React
```jsx
import React, {useState, useEffect} from 'react';
import {useStripe} from '@stripe/react-stripe-js';
const PaymentStatus = () => {
const stripe = useStripe();
const [message, setMessage] = useState(null);
useEffect(() => {
if (!stripe) {
return;
}
// Retrieve the "payment_intent_client_secret" query parameter appended to
// your return_url by Stripe.js
const clientSecret = new URLSearchParams(window.location.search).get(
'payment_intent_client_secret'
);
// Retrieve the PaymentIntent
stripe
.retrievePaymentIntent(clientSecret)
.then(({paymentIntent}) => {
// Inspect the PaymentIntent `status` to indicate the status of the payment
// to your customer.
//
// Some payment methods will [immediately succeed or fail][0] upon
// confirmation, while others will first enter a `processing` state.
//
// [0]: https://stripe.com/docs/payments/payment-methods#payment-notification
switch (paymentIntent.status) {
case 'succeeded':
setMessage('Success! Payment received.');
break;
case 'processing':
setMessage("Payment processing. We'll update you when payment is received.");
break;
case 'requires_payment_method':
// Redirect your user back to your payment page to attempt collecting
// payment again
setMessage('Payment failed. Please try another payment method.');
break;
default:
setMessage('Something went wrong.');
break;
}
});
}, [stripe]);
return message;
};
export default PaymentStatus;
```
## Gerenciar eventos pós-pagamento [Lado do servidor]
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 a [ferramenta Dashboard webhook](https://dashboard.stripe.com/webhooks) ou siga o [guia de webhooks](https://docs.stripe.com/webhooks/quickstart.md) para receber esses eventos e executar ações, como enviar um e-mail de confirmação do pedido ao cliente, registrar a venda em um banco de dados ou iniciar um fluxo de trabalho de envio.
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 sua integração para escutar eventos assíncronos é o que permite a você aceitar [diferentes tipos de formas de pagamento](https://stripe.com/payments/payment-methods-guide) com uma única integração.
Além de gerenciar o evento `payment_intent.succeeded`, recomendamos gerenciar esses outros eventos ao coletar pagamentos com o Element Pagamento:
| Evento | Descrição | Ação |
| ------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [payment_intent.succeeded](https://docs.stripe.com/api/events/types.md?lang=php#event_types-payment_intent.succeeded) | Enviado quando um cliente conclui um pagamento com êxito. | Envie ao cliente uma confirmação de pedido e *processe* (Fulfillment is the process of providing the goods or services purchased by a customer, typically after payment is collected) o pedido. |
| [payment_intent.processing](https://docs.stripe.com/api/events/types.md?lang=php#event_types-payment_intent.processing) | Enviado quando um cliente inicia um pagamento, mas o pagamento ainda precisa ser concluído. Esse evento costuma ser enviado quando um cliente inicia um débito bancário. Ele é seguido por um evento `payment_intent.succeeded` ou `payment_intent.payment_failed` no futuro. | Envie ao cliente uma confirmação do pedido que indica que o pagamento está pendente. Para produtos digitais, pode ser necessário executar o pedido antes de aguardar a conclusão do pagamento. |
| [payment_intent.payment_failed](https://docs.stripe.com/api/events/types.md?lang=php#event_types-payment_intent.payment_failed) | Enviado quando um cliente tenta fazer um pagamento, mas o pagamento falha. | Se um pagamento passa de `processing` para `payment_failed`, ofereça ao cliente outra tentativa para pagar. |
## Testar a integração
#### Cartões
| Número do cartão | Cenário | Como testar |
| ------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------- |
| 4242424242424242 | O pagamento com cartão é bem-sucedido e não precisa de autenticação. | Preencha o formulário do cartão de crédito usando o número do cartão de crédito com qualquer validade, CVC e código postal. |
| 4000002500003155 | O pagamento com cartão precisa de *autenticação* (Strong Customer Authentication (SCA) is a regulatory requirement in effect as of September 14, 2019, that impacts many European online payments. It requires customers to use two-factor authentication like 3D Secure to verify their purchase). | Preencha o formulário do cartão de crédito usando o número do cartão de crédito com qualquer validade, CVC e código postal. |
| 4000000000009995 | O cartão é recusado com um código de recusa como `insufficient_funds`. | Preencha o formulário do cartão de crédito usando o número do cartão de crédito com qualquer validade, CVC e código postal. |
| 6205500000000000004 | O cartão UnionPay tem um comprimento variável de 13 a 19 dígitos. | Preencha o formulário do cartão de crédito usando o número do cartão de crédito com qualquer validade, CVC e código postal. |
#### Carteiras
| Forma de pagamento | Cenário | Como testar |
| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Alipay | O cliente paga com uma forma de pagamento baseada em redirecionamento e [notificação imediata](https://docs.stripe.com/payments/payment-methods.md#payment-notification). | Escolha qualquer forma de pagamento baseada em redirecionamento, preencha os dados obrigatórios e confirme o pagamento. Em seguida, clique em **Concluir o pagamento de teste** na página de redirecionamento. |
#### Débito bancário autenticado
| Forma de pagamento | Cenário | Como testar |
| ------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Débito automático BECS | O cliente paga com débito automático BECS. | Preencha o formulário usando o número de conta `900123456` e BSB `000000`. Inicialmente, o status do PaymentIntent muda para `processing` e, 3 minutos depois, para `succeeded`. |
| Débito automático BECS | O pagamento do cliente falha com um código de erro `account_closed`. | Preencha o formulário usando o número da conta `111111113` e BSB `000000`. |
| Bancontact, EPS, iDEAL, e Przelewy24 | Seu cliente não faz a autenticação na página de redirecionamento de uma forma de pagamento baseada em redirecionamento e notificação imediata. | Escolha qualquer forma de pagamento baseada em redirecionamento, preencha os dados obrigatórios e confirme o pagamento. Em seguida, clique em **Falhar pagamento de teste** na página de redirecionamento. |
| Pay by Bank | O cliente paga com uma forma de pagamento baseada em redirecionamento e [notificação posterior](https://docs.stripe.com/payments/payment-methods.md#payment-notification). | Escolha a forma de pagamento, preencha os dados obrigatórios e confirme o pagamento. Em seguida, clique em **Concluir o pagamento de teste** na página de redirecionamento. |
| Pay by Bank | Seu cliente não faz a autenticação na página de redirecionamento de uma forma de pagamento baseada em redirecionamento e notificação posterior. | Escolha a forma de pagamento, preencha os dados obrigatórios e confirme o pagamento. Em seguida, clique em **Falhar o pagamento de teste** na página de redirecionamento. |
| BLIK | Os pagamentos BLIK falham de várias formas: falhas imediatas (por exemplo, o código está vencido ou inválido), erros atrasados (o banco recusa) ou limites de tempo (o cliente não respondeu a tempo). | Use padrões de e-mail para [simular as diferentes falhas.](https://docs.stripe.com/payments/blik/accept-a-payment.md#simulate-failures) |
#### Débitos bancários
| Forma de pagamento | Cenário | Como testar |
| ---------------------- | ------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Débito automático SEPA | O cliente paga com débito automático SEPA. | Preencha o formulário usando o número de conta `AT321904300235473204`. Inicialmente, o status do PaymentIntent muda para processando e, três minutos depois, para bem-sucedido. |
| Débito automático SEPA | O status da intenção de pagamento do cliente muda de `processing` para `requires_payment_method`. | Preencha o formulário usando o número de conta `AT861904300235473202`. |
#### Boletos
| Forma de pagamento | Cenário | Como testar |
| ------------------ | ------------------------------------------------ | ---------------------------------------------------------------------------------------------- |
| Boleto, OXXO | Seu cliente paga com um boleto ou uma guia OXXO. | Selecione boleto ou OXXO como forma de pagamento e envie o pagamento. Feche o diálogo exibido. |
Consulte [Testes](https://docs.stripe.com/testing.md) para obter mais informações sobre como testar sua integração.
## Optional: Habilitar formas de pagamento adicionais
Navegue para [Gerenciar formas de pagamento para suas contas conectadas](https://dashboard.stripe.com/settings/payment_methods/connected_accounts) no Dashboard para configurar quais formas de pagamento suas contas conectadas aceitam. As alterações nas configurações padrão se aplicam a todas as contas conectadas novas e existentes.
Consulte os seguintes recursos para obter informações sobre formas de pagamento:
- [Um guia de formas de pagamento](https://stripe.com/payments/payment-methods-guide#choosing-the-right-payment-methods-for-your-business) para ajudar você a escolher as formas de pagamento corretas para sua plataforma.
- [Funções da conta](https://docs.stripe.com/connect/account-capabilities.md) para assegurar que as formas de pagamento escolhidas funcionem para suas contas conectadas.
- Tabelas de [suporte a formas de pagamento e produtos](https://docs.stripe.com/payments/payment-methods/payment-method-support.md#product-support) para assegurar que suas formas de pagamento escolhidas funcionem para seus produtos da Stripe e fluxos de pagamento.
Para cada forma de pagamento, você pode selecionar uma das seguintes opções no menu suspenso:
| |
| |
| **Ativadas por padrão** | Suas contas conectadas aceitam esta forma de pagamento durante o checkout. Algumas formas de pagamento podem ser desativadas ou bloqueadas. Isso ocorre porque suas contas conectadas com *acesso ao Stripe Dashboard* (Platforms can provide connected accounts with access to the full Stripe Dashboard or the Express Dashboard. Otherwise, platforms build an interface for connected accounts using embedded components or the Stripe API) precisam ativá-las em sua página de configurações. |
| **Desativadas por padrão** | Suas contas conectadas não aceitam esta forma de pagamento durante o checkout. Se você permitir que contas conectadas com *acessem o Stripe Dashboard* (Platforms can provide connected accounts with access to the full Stripe Dashboard or the Express Dashboard. Otherwise, platforms build an interface for connected accounts using embedded components or the Stripe API) para gerenciar suas próprias formas de pagamento, elas podem ativar esse recurso. |
| **Bloqueadas** | Suas contas conectadas não aceitam esta forma de pagamento durante o checkout. Se você permitir que contas conectadas com *acessem o Stripe Dashboard* (Platforms can provide connected accounts with access to the full Stripe Dashboard or the Express Dashboard. Otherwise, platforms build an interface for connected accounts using embedded components or the Stripe API) para gerenciar suas próprias formas de pagamento, elas não têm a opção para ativar esse recurso. |
Opções de formas de pagamento
Se fizer uma alteração em uma forma de pagamento, você deve clicar em **Revisar alterações** na barra inferior da tela e em **Salvar e aplicar** para atualizar suas contas conectadas.
Salvar diálogo
### Permitir que contas conectadas gerenciem formas de pagamento
A Stripe recomenda permitir que as contas conectadas personalizem suas próprias formas de pagamento. Esta opção permite que cada conta conectada com *acesso ao Stripe Dashboard* (Platforms can provide connected accounts with access to the full Stripe Dashboard or the Express Dashboard. Otherwise, platforms build an interface for connected accounts using embedded components or the Stripe API) para ver e atualizar sua página de [formas de pagamento](https://dashboard.stripe.com/settings/payment_methods). Somente os proprietários das contas conectadas podem personalizar as formas de pagamento. O Stripe Dashboard exibe o conjunto de padrões de forma de pagamento que você aplicou a todas as contas conectadas novas e existentes. Suas contas conectadas podem sobrepor esses padrões, excluindo as formas de pagamento que você bloqueou.
Marque a caixa de seleção **Personalização da conta** para habilitar essa opção. Você deve clicar em **Revisar alterações** na barra inferior da tela e selecionar **Salvar e aplicar** para atualizar essa configuração.
Caixa de seleção de personalização da conta
### Funções das formas de pagamento
Para permitir que suas contas conectadas aceitem formas de pagamento adicionais, suas `Accounts` devem ter recursos de formas de pagamento ativas.
Se você selecionou a opção “On by default” (ativado por padrão) como método de pagamento em[Gerencie formas de pagamento para suas contas conectadas](https://dashboard.stripe.com/settings/payment_methods/connected_accounts), a Stripe solicita automaticamente a funcionalidade necessário para contas conectadas novas e existentes, caso atendam aos requisitos de verificação. Se a conta conectada não atender aos requisitos ou se você quiser ter controle direto, pode solicitação manualmente a funcionalidade no Dashboard ou na API.
A maioria das formas de pagamento possui os mesmos requisitos de verificação que a funcionalidade `card_payments`, com algumas restrições e exceções. A[tabela de formas de pagamento](https://docs.stripe.com/connect/account-capabilities.md#payment-methods) lista os métodos de pagamento que requerem verificação adicional.
#### Dashboard
[Encontre uma conta conectada](https://docs.stripe.com/connect/dashboard/managing-individual-accounts.md#finding-accounts) no Dashboard para editar suas capacidades e visualizar os requisitos de verificação pendentes.
#### API
Para uma conta conectada existente, você pode [listar](https://docs.stripe.com/api/capabilities/list.md) as funções existentes decidir se precisa solicitar funções adicionais.
```curl
curl https://api.stripe.com/v1/accounts/{{CONNECTEDACCOUNT_ID}}/capabilities \
-u "<>:"
```
Solicite funções adicionais [atualizando](https://docs.stripe.com/api/capabilities/update.md) as funções de cada conta conectada.
```curl
curl https://api.stripe.com/v1/accounts/{{CONNECTEDACCOUNT_ID}}/capabilities/us_bank_account_ach_payments \
-u "<>:" \
-d requested=true
```
Pode haver um atraso antes que a função solicitada se torne ativa. Se a função tiver algum requisito de ativação, ele será incluído nas matrizes de `requirements`.
## Coletar tarifas
Como plataforma, você pode cobrar de suas contas conectadas uma parte de cada transação na forma de tarifas da plataforma. Você pode definir a tarifa da plataforma das seguintes maneiras:
- Use a [ferramenta de preços da plataforma](https://docs.stripe.com/connect/platform-pricing-tools.md) para definir e testar regras de preços. No momento, esse recurso no-code no Stripe Dashboard só está disponível para plataformas responsáveis pelo pagamento das tarifas da Stripe.
- Especifique tarifas de aplicação diretamente em um [PaymentIntent](https://docs.stripe.com/api/payment_intents/object.md). As tarifas definidas com esse método substituem a lógica de precificação especificada na Platform Pricing Tool.
Sua plataforma pode cobrar uma tarifa da plataforma com as seguintes limitações:
- O valor de `application_fee_amount` deve ser positivo e inferior ao o valor da cobrança. A tarifa da plataforma recolhida é limitada ao valor capturado da cobrança.
- Não há tarifas adicionais da Stripe sobre a própria tarifa da plataforma.
- Em conformidade com os requisitos regulatórios e de conformidade do Brasil, plataformas sediadas fora do Brasil com contas conectadas brasileiras não podem recolher tarifas da plataforma por meio da Stripe.
- A moeda de `application_fee_amount` depende de alguns fatores de [várias moedas](https://docs.stripe.com/connect/currencies.md).
A [BalanceTransaction](https://docs.stripe.com/api.md#balance_transaction_retrieve) da cobrança resultante inclui um detalhamento das tarifas, tanto da Stripe quanto das tarifas da plataforma. Para proporcionar uma melhor experiência de relatórios, a cobrança de uma tarifa gera um objeto [ApplicationFee](https://docs.stripe.com/api/application_fees/object.md). Use a propriedade `amount`t no objeto `ApplicationFee` para fins de relatório.
Você pode visualizar as tarifas da plataforma na seção [tarifas cobradas](https://dashboard.stripe.com/connect/application_fees) do Dashboard.
> Por padrão, as tarifas da plataforma para cobranças diretas são criadas de forma assíncrona. Se você expandir o objeto `application_fee` em uma solicitação de criação de cobrança, a tarifa da plataforma será criada de forma síncrona como parte dessa solicitação. Somente expanda o objeto `application_fee` se for necessário, pois isso aumenta a latência da solicitação.
>
> Para receber notificações de objetos `ApplicationFee` criados de forma assíncrona, escute o evento de Webhook [application_fee.created](https://docs.stripe.com/api/events/types.md#event_types-application_fee.created).
Integre a IU de pagamento pré-criada da Stripe no checkout do seu aplicativo iOS com a classe [PaymentSheet](https://stripe.dev/stripe-ios/stripe-paymentsheet/Classes/PaymentSheet.html). Veja nosso exemplo de integração [no GitHub](https://github.com/stripe/stripe-ios/tree/master/Example/PaymentSheet%20Example).
## Configurar a Stripe [Lado do servidor] [Lado do cliente]
Primeiro, você precisa de uma conta Stripe. [Cadastre-se agora](https://dashboard.stripe.com/register).
### Lado do servidor
Esta integração exige que os endpoints do seu servidor se comuniquem com a API da Stripe. Use nossas bibliotecas oficiais para acessar a API da Stripe pelo seu servidor:
#### 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'
```
### Lado do cliente
O [SDK da Stripe para iOS](https://github.com/stripe/stripe-ios) é de código aberto, [totalmente documentado](https://stripe.dev/stripe-ios/index.html) e compatível com aplicativos que aceitam iOS 13 ou versões mais recentes.
#### Gerenciador de pacotes Swift
Para instalar o SDK, siga estas etapas:
1. No Xcode, selecione **Arquivo** > **Adicionar dependências de pacote…** e insira `https://github.com/stripe/stripe-ios-spm` como URL do repositório.
1. Selecione o número da última versão da nossa [página de lançamentos](https://github.com/stripe/stripe-ios/releases).
1. Adicione o produto **StripePaymentSheet** ao [alvo do seu aplicativo](https://developer.apple.com/documentation/swift_packages/adding_package_dependencies_to_your_app).
#### CocoaPods
1. Se ainda não o fez, instale a versão mais recente do [CocoaPods](https://guides.cocoapods.org/using/getting-started.html).
1. Se não tiver um [Podfile](https://guides.cocoapods.org/syntax/podfile.html), execute o seguinte comando para criar um:
```bash
pod init
```
1. Adicione esta linha ao seu `Podfile`:
```podfile
pod 'StripePaymentSheet'
```
1. Execute o seguinte comando:
```bash
pod install
```
1. Não se esqueça de usar o arquivo `.xcworkspace` para abrir seu projeto em Xcode, em vez do arquivo `.xcodeproj`, daqui em diante.
1. No futuro, para atualizar para a versão mais recente do SDK, execute:
```bash
pod update StripePaymentSheet
```
#### Carthage
1. Se ainda não o fez, instale a versão mais recente do [Carthage](https://github.com/Carthage/Carthage#installing-carthage).
1. Adicione esta linha ao seu `Cartfile`:
```cartfile
github "stripe/stripe-ios"
```
1. Siga as [instruções de instalação do Carthage](https://github.com/Carthage/Carthage#if-youre-building-for-ios-tvos-or-watchos). Certifique-se de integrar todas as estruturas necessárias listadas [here](https://github.com/stripe/stripe-ios/tree/master/StripePaymentSheet/README.md#manual-linking).
1. No futuro, para atualizar para a versão mais recente do SDK, execute o seguinte comando:
```bash
carthage update stripe-ios --platform ios
```
#### Estrutura manual
1. Vá até a nossa [página de lançamentos do GitHub](https://github.com/stripe/stripe-ios/releases/latest) e baixe e descompacte o **Stripe.xcframework.zip**.
1. Arraste **StripePaymentSheet.xcframework** até a seção **Embedded Binaries** das configurações **General** no seu projeto Xcode. Certifique-se de selecionar **Copy items if needed**.
1. Repita a etapa 2 para todas as estruturas necessárias listadas [here](https://github.com/stripe/stripe-ios/tree/master/StripePaymentSheet/README.md#manual-linking).
1. No futuro, para atualizar para a versão mais recente do nosso SDK, repita as etapas 1 a 3.
> Para obter mais informações sobre a versão mais recente e as versões anteriores do SDK, consulte a página [Lançamentos](https://github.com/stripe/stripe-ios/releases) no GitHub. Para receber notificações quando um novo lançamento for publicado, [assista aos lançamentos](https://help.github.com/en/articles/watching-and-unwatching-releases-for-a-repository#watching-releases-for-a-repository) do repositório.
Configure o SDK com sua [chave publicável da Stripe](https://dashboard.stripe.com/test/apikeys) na inicialização do aplicativo. Isso permite que seu aplicativo faça solicitações à API da Stripe .
#### Swift
```swift
import UIKitimportStripePaymentSheet
@main
class AppDelegate: UIResponder, UIApplicationDelegate {
func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {StripeAPI.defaultPublishableKey = "<>"
// do any other necessary launch configuration
return true
}
}
```
> Use suas [chaves de teste](https://docs.stripe.com/keys.md#obtain-api-keys) enquanto testa e desenvolve, e suas chaves de [modo de produção](https://docs.stripe.com/keys.md#test-live-modes) quando publicar seu aplicativo.
## Adicionar um endpoint [Lado do servidor]
> #### Nota
>
> Para exibir o PaymentSheet antes de criar um PaymentIntent, consulte [Colete os dados de pagamento antes de criar um Intent](https://docs.stripe.com/payments/accept-a-payment-deferred.md?type=payment).
Se a sua plataforma Connect utiliza [Contas configuradas pelo cliente](https://docs.stripe.com/api/v2/core/accounts/create.md#v2_create_accounts-configuration-customer), utilize o nosso [guia](https://docs.stripe.com/connect/use-accounts-as-customers.md) para substituir as referências a `Cliente` e eventos no seu código pelas referências equivalentes da API Accounts v2.
Esta integração usa três objetos da API da Stripe:
1. [PaymentIntent](https://docs.stripe.com/api/payment_intents.md): A Stripe usa isso para representar sua intenção de coletar o pagamento de um cliente, acompanhando suas tentativas de cobrança e alterações no estado do pagamento durante todo o processo.
1. (Opcional) [Customer](https://docs.stripe.com/api/customers.md): Para configurar uma forma de pagamento para pagamentos futuros, vincule-a a um *Customer* (Customer objects represent customers of your business. They let you reuse payment methods and give you the ability to track multiple payments). Crie um objeto Customer quando o cliente abrir uma conta na sua empresa. Se o cliente pagar como convidado, você pode criar o objeto Customer antes do pagamento e associá-lo à sua representação interna da conta do cliente, mais tarde.
1. (Opcional) [CustomerSession](https://docs.stripe.com/api/customer_sessions.md): Os dados do objeto Customer são confidenciais e não podem ser recuperados diretamente do aplicativo. Uma CustomerSession concede ao SDK acesso temporário com escopo definido ao cliente e fornece opções de configuração adicionais. Consulte uma lista completa de [opções de configuração](https://docs.stripe.com/api/customer_sessions/create.md#create_customer_session-components).
> Se você nunca salva cartões para um cliente e não permite que clientes retornando reutilizem cartões salvos, é possível omitir os objetos cliente e CustomerSession da sua integração.
Por motivos de segurança, o aplicativo não pode criar esses objetos. Para isso, adicione um endpoint ao servidor para:
1. Recuperar ou criar um Customer.
1. Cria uma [CustomerSession](https://docs.stripe.com/api/customer_sessions.md) para o cliente.
1. Cria um PaymentIntent com o [valor](https://docs.stripe.com/api/payment_intents/create.md#create_payment_intent-amount), a [moeda](https://docs.stripe.com/api/payment_intents/create.md#create_payment_intent-currency) e o [cliente](https://docs.stripe.com/api/payment_intents/create.md#create_payment_intent-customer).
1. Retorna o *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)) do Payment Intent, o `client_secret` da CustomerSession, o [id](https://docs.stripe.com/api/customers/object.md#customer_object-id) do Cliente e sua [chave publicável](https://dashboard.stripe.com/apikeys) para seu aplicativo.
As formas de pagamento mostradas aos clientes durante o processo de checkout também são incluídas no PaymentIntent. Você pode permitir que a Stripe obtenha as formas de pagamento das configurações do Dashboard ou listá-las manualmente. Independentemente da opção escolhida, saiba que a moeda passada no PaymentIntent filtra as formas de pagamento mostradas para o cliente. Por exemplo, se você passar EUR no `eur` e a OXXO estiver ativada no Dashboard, a OXXO não será exibida ao cliente porque a OXXO não aceita pagamentos em `eur`.
Se sua integração não exige uma opção baseada em código para oferecer formas de pagamento, a Stripe recomenda a opção automática. Isso ocorre porque a Stripe avalia a moeda, as restrições de forma de pagamento e outros parâmetros para determinar a lista de formas de pagamento aceitas. Priorizamos as formas de formas de pagamento que aumentam a conversão e que são mais relevantes para a moeda e a localização do cliente.
#### Gerenciar formas de pagamento no Dashboard
Você pode gerenciar formas de pagamento no [Dashboard](https://dashboard.stripe.com/settings/payment_methods). A Stripe processa a devolução de formas de pagamento qualificadas com base em fatores como valor, moeda e fluxo de pagamento da transação. O PaymentIntent é criado usando as formas de pagamento configuradas no Dashboard. Se não quiser usar o Dashboard ou se quiser especificar formas de pagamento manualmente, você pode listá-las usando o atributo `payment_method_types`.
#### curl
```bash
# Create a Customer (use an existing Customer ID if this is a returning customer)
curl https://api.stripe.com/v1/customers \
-u <>: \
-X "POST" \
-H "Stripe-Account: {{CONNECTED_ACCOUNT_ID}}"
# Create an CustomerSession for the Customer
curl https://api.stripe.com/v1/customer_sessions \
-u <>: \
-X "POST" \
-d "customer"="{{CUSTOMER_ID}}" \
-d "components[mobile_payment_element][enabled]"=true \
-d "components[mobile_payment_element][features][payment_method_save]"=enabled \
-d "components[mobile_payment_element][features][payment_method_redisplay]"=enabled \
-d "components[mobile_payment_element][features][payment_method_remove]"=enabled
# Create a PaymentIntent
curl https://api.stripe.com/v1/payment_intents \
-u <>: \
-H "Stripe-Account: {{CONNECTED_ACCOUNT_ID}}"
-X "POST" \
-d "customer"="{{CUSTOMER_ID}}" \
-d "amount"=1099 \
-d "currency"="eur" \
# In the latest version of the API, specifying the `automatic_payment_methods` parameter
# is optional because Stripe enables its functionality by default.
-d "automatic_payment_methods[enabled]"=true \
-d application_fee_amount="123" \
```
#### Listar manualmente as formas de pagamento
#### curl
```bash
# Create a Customer (use an existing Customer ID if this is a returning customer)
curl https://api.stripe.com/v1/customers \
-u <>: \
-X "POST" \
-H "Stripe-Account: {{CONNECTED_ACCOUNT_ID}}"
# Create an CustomerSession for the Customer
curl https://api.stripe.com/v1/customer_sessions \
-u <>: \
-X "POST" \
-d "customer"="{{CUSTOMER_ID}}" \
-d "components[mobile_payment_element][enabled]"=true \
-d "components[mobile_payment_element][features][payment_method_save]"=enabled \
-d "components[mobile_payment_element][features][payment_method_redisplay]"=enabled \
-d "components[mobile_payment_element][features][payment_method_remove]"=enabled
# Create a PaymentIntent
curl https://api.stripe.com/v1/payment_intents \
-u <>: \
-H "Stripe-Account: {{CONNECTED_ACCOUNT_ID}}"
-X "POST" \
-d "customer"="{{CUSTOMER_ID}}" \
-d "amount"=1099 \
-d "currency"="eur" \
-d "payment_method_types[]"="bancontact" \
-d "payment_method_types[]"="card" \
-d "payment_method_types[]"="ideal" \
-d "payment_method_types[]"="klarna" \
-d "payment_method_types[]"="sepa_debit" \
-d application_fee_amount="123" \
```
> A forma de pagamento precisa aceitar a moeda passada no PaymentIntent. Além disso, sua empresa precisa estar estabelecida em um dos países aceitos pela forma de pagamento. Consulte a página [Opções de integração de formas de pagamento](https://docs.stripe.com/payments/payment-methods/integration-options.md) para obter mais detalhes sobre o que é aceito.
## Integrar a descrição da compra [Lado do cliente]
Para exibir o Payment Element para dispositivos móveis na tela de checkout, não se esqueça de:
- Mostrar os produtos que o cliente está comprando e o valor total
- Usar o [Address Element](https://docs.stripe.com/elements/address-element.md?platform=ios) para coletar todos os dados de envio necessários do cliente
- Adicionar um botão de checkout para exibir a IU da Stripe
#### UIKit
Na tela checkout do aplicativo, busque o segredo do cliente PaymentIntent, o segredo do cliente CustomerSession, a ID do cliente e a chave publicável do endpoint que você criou na etapa anterior. Use`STPAPIClient.shared` para definir sua chave publicável e inicialize o[PaymentSheet](https://stripe.dev/stripe-ios/stripe-paymentsheet/Classes/PaymentSheet.html).
Em seguida, defina `STPAPIClient.shared.stripeAccount` ao ID da conta conectada.
#### iOS (Swift)
```swift
import UIKit@_spi(CustomerSessionBetaAccess) import StripePaymentSheet
class CheckoutViewController: UIViewController {
@IBOutlet weak var checkoutButton: UIButton!
var paymentSheet: PaymentSheet?
let backendCheckoutUrl = URL(string: "Your backend endpoint/payment-sheet")! // Your backend endpoint
override func viewDidLoad() {
super.viewDidLoad()
checkoutButton.addTarget(self, action: #selector(didTapCheckoutButton), for: .touchUpInside)
checkoutButton.isEnabled = false
// MARK: Fetch the PaymentIntent client secret, CustomerSession client secret, Customer ID, and publishable key
var request = URLRequest(url: backendCheckoutUrl)
request.httpMethod = "POST"
let task = URLSession.shared.dataTask(with: request, completionHandler: { [weak self] (data, response, error) in
guard let data = data,
let json = try? JSONSerialization.jsonObject(with: data, options: []) as? [String : Any],
let customerId = json["customer"] as? String,
let customerSessionClientSecret = json["customerSessionClientSecret"] as? String,
let paymentIntentClientSecret = json["paymentIntent"] as? String,
let publishableKey = json["publishableKey"] as? String,
let self = self else {
// Handle error
return
}
STPAPIClient.shared.publishableKey = publishableKeySTPAPIClient.shared.stripeAccount = ""{{CONNECTED_ACCOUNT_ID}}""// MARK: Create a PaymentSheet instance
var configuration = PaymentSheet.Configuration()
configuration.merchantDisplayName = "Example, Inc."
configuration.customer = .init(id: customerId, customerSessionClientSecret: customerSessionClientSecret)
// Set `allowsDelayedPaymentMethods` to true if your business handles
// delayed notification payment methods like US bank accounts.
configuration.allowsDelayedPaymentMethods = true
self.paymentSheet = PaymentSheet(paymentIntentClientSecret:paymentIntentClientSecret, configuration: configuration)
DispatchQueue.main.async {
self.checkoutButton.isEnabled = true
}
})
task.resume()
}
}
```
Quando o cliente toca no botão **Checkout**, invoque `present` para apresentar a PaymentSheet. Após o cliente concluir o pagamento, a descrição é descartada e o bloco de conclusão é invocado com [PaymentSheetResult](https://stripe.dev/stripe-ios/stripe-paymentsheet/Enums/PaymentSheetResult.html).
#### iOS (Swift)
```swift
@objc
func didTapCheckoutButton() {
// MARK: Start the checkout process
paymentSheet?.present(from: self) { paymentResult in
// MARK: Handle the payment result
switch paymentResult {
case .completed:
print("Your order is confirmed")
case .canceled:
print("Canceled!")
case .failed(let error):
print("Payment failed: \(error)")
}
}
}
```
#### SwiftUI
Crie um modelo `ObservableObject` para sua tela de checkout. Esse modelo publica uma [PaymentSheet](https://stripe.dev/stripe-ios/stripe-paymentsheet/Classes/PaymentSheet.html) e um [PaymentSheetResult](https://stripe.dev/stripe-ios/stripe-paymentsheet/Enums/PaymentSheetResult.html).
```swift
import StripePaymentSheet
import SwiftUI
class CheckoutViewModel: ObservableObject {
let backendCheckoutUrl = URL(string: "Your backend endpoint/payment-sheet")! // Your backend endpoint
@Published var paymentSheet: PaymentSheet?
@Published var paymentResult: PaymentSheetResult?
}
```
Busque a segredo do cliente PaymentIntent, o segredo do cliente CustomerSession, a ID do cliente e a chave publicável do endpoint que você criou na etapa anterior. Use`STPAPIClient.shared` para definir sua chave publicável e inicialize o[PaymentSheet](https://stripe.dev/stripe-ios/stripe-paymentsheet/Classes/PaymentSheet.html).
Em seguida, defina `STPAPIClient.shared.stripeAccount` ao ID da conta conectada.
```swift
@_spi(CustomerSessionBetaAccess) import StripePaymentSheet
import SwiftUI
class CheckoutViewModel: ObservableObject {
let backendCheckoutUrl = URL(string: "Your backend endpoint/payment-sheet")! // Your backend endpoint
@Published var paymentSheet: PaymentSheet?
@Published var paymentResult: PaymentSheetResult?
func preparePaymentSheet() {
// MARK: Fetch thePaymentIntent and Customer information from the backend
var request = URLRequest(url: backendCheckoutUrl)
request.httpMethod = "POST"
let task = URLSession.shared.dataTask(with: request, completionHandler: { [weak self] (data, response, error) in
guard let data = data,
let json = try? JSONSerialization.jsonObject(with: data, options: []) as? [String : Any],
let customerId = json["customer"] as? String,
let customerSessionClientSecret = json["customerSessionClientSecret"] as? String,
letpaymentIntentClientSecret = json["paymentIntent"] as? String,
let publishableKey = json["publishableKey"] as? String,
let self = self else {
// Handle error
return
}
STPAPIClient.shared.publishableKey = publishableKeySTPAPIClient.shared.stripeAccount = ""{{CONNECTED_ACCOUNT_ID}}""// MARK: Create a PaymentSheet instance
var configuration = PaymentSheet.Configuration()
configuration.merchantDisplayName = "Example, Inc."
configuration.customer = .init(id: customerId, customerSessionClientSecret: customerSessionClientSecret)
// Set `allowsDelayedPaymentMethods` to true if your business handles
// delayed notification payment methods like US bank accounts.
configuration.allowsDelayedPaymentMethods = true
DispatchQueue.main.async {
self.paymentSheet = PaymentSheet(paymentIntentClientSecret:paymentIntentClientSecret, configuration: configuration)
}
})
task.resume()
}
}
struct CheckoutView: View {
@ObservedObject var model = CheckoutViewModel()
var body: some View {
VStack {
if model.paymentSheet != nil {
Text("Ready to pay.")
} else {
Text("Loading…")
}
}.onAppear { model.preparePaymentSheet() }
}
}
```
Adicione um [PaymentSheet.PaymentButton](https://stripe.dev/stripe-ios/stripe-paymentsheet/Classes/PaymentSheet/PaymentButton.html) à sua `View`. O comportamento é similar a um `Button` SwiftUI, que permite ser personalizado com a adição de uma `View`. Quando você clica no botão, o PaymentSheet é exibido. Depois que você conclui o pagamento, a Stripe descarta a PaymentSheet e chama o gerenciador `onCompletion` com um objeto [PaymentSheetResult](https://stripe.dev/stripe-ios/stripe-paymentsheet/Enums/PaymentSheetResult.html).
```swift
@_spi(CustomerSessionBetaAccess) import StripePaymentSheet
import SwiftUI
class CheckoutViewModel: ObservableObject {
let backendCheckoutUrl = URL(string: "Your backend endpoint/payment-sheet")! // Your backend endpoint
@Published var paymentSheet: PaymentSheet?
@Published var paymentResult: PaymentSheetResult?
func preparePaymentSheet() {
// MARK: Fetch the PaymentIntent and Customer information from the backend
var request = URLRequest(url: backendCheckoutUrl)
request.httpMethod = "POST"
let task = URLSession.shared.dataTask(with: request, completionHandler: { [weak self] (data, response, error) in
guard let data = data,
let json = try? JSONSerialization.jsonObject(with: data, options: []) as? [String : Any],
let customerId = json["customer"] as? String,
let customerSessionClientSecret = json["customerSessionClientSecret"] as? String,
let paymentIntentClientSecret = json["paymentIntent"] as? String,
let publishableKey = json["publishableKey"] as? String,
let self = self else {
// Handle error
return
}
STPAPIClient.shared.publishableKey = publishableKey
STPAPIClient.shared.stripeAccount = ""{{CONNECTED_ACCOUNT_ID}}""
// MARK: Create a PaymentSheet instance
var configuration = PaymentSheet.Configuration()
configuration.merchantDisplayName = "Example, Inc."
configuration.customer = .init(id: customerId, customerSessionClientSecret: customerSessionClientSecret)
// Set `allowsDelayedPaymentMethods` to true if your business can handle payment methods
// that complete payment after a delay, like SEPA Debit and Sofort.
configuration.allowsDelayedPaymentMethods = true
DispatchQueue.main.async {
self.paymentSheet = PaymentSheet(paymentIntentClientSecret: paymentIntentClientSecret, configuration: configuration)
}
})
task.resume()
}
func onPaymentCompletion(result: PaymentSheetResult) {
self.paymentResult = result
}
}
struct CheckoutView: View {
@ObservedObject var model = CheckoutViewModel()
var body: some View {
VStack {if let paymentSheet = model.paymentSheet {
PaymentSheet.PaymentButton(
paymentSheet: paymentSheet,
onCompletion: model.onPaymentCompletion
) {
Text("Buy")
}
} else {
Text("Loading…")
}if let result = model.paymentResult {
switch result {
case .completed:
Text("Payment complete")
case .failed(let error):
Text("Payment failed: \(error.localizedDescription)")
case .canceled:
Text("Payment canceled.")
}
}
}.onAppear { model.preparePaymentSheet() }
}
}
```
Se `PaymentSheetResult` for `.completed`, informe ao usuário (por exemplo, exibindo uma tela de confirmação de pedido).
Configurar `allowsDelayedPaymentMethods` como verdadeiro permite formas de pagamento de [notificação assíncrona](https://docs.stripe.com/payments/payment-methods.md#payment-notification) como contas bancárias dos EUA. Para essas formas de pagamento, o status final do pagamento não é conhecido quando o `PaymentSheet` é concluído, sendo efetivado ou não posteriormente. Se você aceitar esses tipos de formas de pagamento, informe o cliente que seu pedido está confirmado e somente processe o pedido (por exemplo, fazendo o envio do produto) quando o pagamento for bem-sucedido.
## Configurar um URL de retorno [Lado do cliente]
O cliente pode sair do seu aplicativo para autenticar (por exemplo, no Safari ou no aplicativo bancário). Para permitir que eles voltem ao seu aplicativo após a autenticação, [configure um esquema de URL personalizado](https://developer.apple.com/documentation/xcode/defining-a-custom-url-scheme-for-your-app) e configure seu aplicativo delegado para encaminhar o URL ao SDK. A Stripe não aceita [links universais](https://developer.apple.com/documentation/xcode/allowing-apps-and-websites-to-link-to-your-content).
#### SceneDelegate
#### Swift
```swift
// This method handles opening custom URL schemes (for example, "your-app://stripe-redirect")
func scene(_ scene: UIScene, openURLContexts URLContexts: Set) {
guard let url = URLContexts.first?.url else {
return
}
let stripeHandled = StripeAPI.handleURLCallback(with: url)
if (!stripeHandled) {
// This was not a Stripe url – handle the URL normally as you would
}
}
```
#### AppDelegate
#### Swift
```swift
// This method handles opening custom URL schemes (for example, "your-app://stripe-redirect")
func application(_ app: UIApplication, open url: URL, options: [UIApplication.OpenURLOptionsKey: Any] = [:]) -> Bool {
let stripeHandled = StripeAPI.handleURLCallback(with: url)
if (stripeHandled) {
return true
} else {
// This was not a Stripe url – handle the URL normally as you would
}
return false
}
```
#### SwiftUI
#### Swift
```swift
@main
struct MyApp: App {
var body: some Scene {
WindowGroup {
Text("Hello, world!").onOpenURL { incomingURL in
let stripeHandled = StripeAPI.handleURLCallback(with: incomingURL)
if (!stripeHandled) {
// This was not a Stripe url – handle the URL normally as you would
}
}
}
}
}
```
## Gerenciar eventos pós-pagamento [Lado do servidor]
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 a [ferramenta Dashboard webhook](https://dashboard.stripe.com/webhooks) ou siga o [guia de webhooks](https://docs.stripe.com/webhooks/quickstart.md) para receber esses eventos e executar ações, como enviar um e-mail de confirmação do pedido ao cliente, registrar a venda em um banco de dados ou iniciar um fluxo de trabalho de envio.
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 sua integração para escutar eventos assíncronos é o que permite a você aceitar [diferentes tipos de formas de pagamento](https://stripe.com/payments/payment-methods-guide) com uma única integração.
Além de gerenciar o evento `payment_intent.succeeded`, recomendamos gerenciar esses outros eventos ao coletar pagamentos com o Element Pagamento:
| Evento | Descrição | Ação |
| ------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [payment_intent.succeeded](https://docs.stripe.com/api/events/types.md?lang=php#event_types-payment_intent.succeeded) | Enviado quando um cliente conclui um pagamento com êxito. | Envie ao cliente uma confirmação de pedido e *processe* (Fulfillment is the process of providing the goods or services purchased by a customer, typically after payment is collected) o pedido. |
| [payment_intent.processing](https://docs.stripe.com/api/events/types.md?lang=php#event_types-payment_intent.processing) | Enviado quando um cliente inicia um pagamento, mas o pagamento ainda precisa ser concluído. Esse evento costuma ser enviado quando um cliente inicia um débito bancário. Ele é seguido por um evento `payment_intent.succeeded` ou `payment_intent.payment_failed` no futuro. | Envie ao cliente uma confirmação do pedido que indica que o pagamento está pendente. Para produtos digitais, pode ser necessário executar o pedido antes de aguardar a conclusão do pagamento. |
| [payment_intent.payment_failed](https://docs.stripe.com/api/events/types.md?lang=php#event_types-payment_intent.payment_failed) | Enviado quando um cliente tenta fazer um pagamento, mas o pagamento falha. | Se um pagamento passa de `processing` para `payment_failed`, ofereça ao cliente outra tentativa para pagar. |
## Testar a integração
#### Cartões
| Número do cartão | Cenário | Como testar |
| ------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------- |
| 4242424242424242 | O pagamento com cartão é bem-sucedido e não precisa de autenticação. | Preencha o formulário do cartão de crédito usando o número do cartão de crédito com qualquer validade, CVC e código postal. |
| 4000002500003155 | O pagamento com cartão precisa de *autenticação* (Strong Customer Authentication (SCA) is a regulatory requirement in effect as of September 14, 2019, that impacts many European online payments. It requires customers to use two-factor authentication like 3D Secure to verify their purchase). | Preencha o formulário do cartão de crédito usando o número do cartão de crédito com qualquer validade, CVC e código postal. |
| 4000000000009995 | O cartão é recusado com um código de recusa como `insufficient_funds`. | Preencha o formulário do cartão de crédito usando o número do cartão de crédito com qualquer validade, CVC e código postal. |
| 6205500000000000004 | O cartão UnionPay tem um comprimento variável de 13 a 19 dígitos. | Preencha o formulário do cartão de crédito usando o número do cartão de crédito com qualquer validade, CVC e código postal. |
#### Débito bancário autenticado
| Forma de pagamento | Cenário | Como testar |
| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Bancontact, iDEAL | Seu cliente não faz a autenticação na página de redirecionamento de uma forma de pagamento baseada em redirecionamento e notificação imediata. | Escolha qualquer forma de pagamento baseada em redirecionamento, preencha os dados obrigatórios e confirme o pagamento. Em seguida, clique em **Falhar pagamento de teste** na página de redirecionamento. |
| Pay by Bank | O cliente paga com uma forma de pagamento baseada em redirecionamento e [notificação posterior](https://docs.stripe.com/payments/payment-methods.md#payment-notification). | Escolha a forma de pagamento, preencha os dados obrigatórios e confirme o pagamento. Em seguida, clique em **Concluir o pagamento de teste** na página de redirecionamento. |
| Pay by Bank | Seu cliente não faz a autenticação na página de redirecionamento de uma forma de pagamento baseada em redirecionamento e notificação posterior. | Escolha a forma de pagamento, preencha os dados obrigatórios e confirme o pagamento. Em seguida, clique em **Falhar o pagamento de teste** na página de redirecionamento. |
| BLIK | Os pagamentos BLIK falham de várias formas: falhas imediatas (por exemplo, o código está vencido ou inválido), erros atrasados (o banco recusa) ou limites de tempo (o cliente não respondeu a tempo). | Use padrões de e-mail para [simular as diferentes falhas.](https://docs.stripe.com/payments/blik/accept-a-payment.md#simulate-failures) |
#### Débitos bancários
| Forma de pagamento | Cenário | Como testar |
| ---------------------- | ------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Débito automático SEPA | O cliente paga com débito automático SEPA. | Preencha o formulário usando o número de conta `AT321904300235473204`. Inicialmente, o status do PaymentIntent muda para processando e, três minutos depois, para bem-sucedido. |
| Débito automático SEPA | O status da intenção de pagamento do cliente muda de `processing` para `requires_payment_method`. | Preencha o formulário usando o número de conta `AT861904300235473202`. |
Consulte [Testes](https://docs.stripe.com/testing.md) para obter mais informações sobre como testar sua integração.
## Habilitar leitura de cartões
Para habilitar o suporte à leitura de cartões no iOS, defina `NSCameraUsageDescription` (**Privacy - Camera Usage Description**) no `Info.plist` do seu aplicativo e informe um motivo para o acesso à câmera (por exemplo, “Para ler cartões”).
## Optional: Ativar Apple Pay
> Se sua tela de checkout tiver um **botão Apple Pay** exclusivo, siga o [guia do Apple Pay](https://docs.stripe.com/apple-pay.md#present-payment-sheet) e use `ApplePayContext` para receber pagamentos pelo botão Apple Pay. Você pode usar `PaymentSheet` para processar outros tipos de forma de pagamento.
### Solicitar um ID de comerciante da Apple
Obtenha um ID de comerciante da Apple [solicitando um novo identificador](https://developer.apple.com/account/resources/identifiers/add/merchant) no site de desenvolvedores da Apple.
Preencha o formulário com descrição e identificador. A descrição é para seu controle e pode ser modificada no futuro. A Stripe recomenda que você use o nome do aplicativo como identificador (por exemplo, `merchant.com.{{YOUR_APP_NAME}}`).
### Criar um certificado Apple Pay
Crie um certificado para criptografia de dados de pagamento pelo aplicativo.
Vá até [Configurações de certificado do iOS](https://dashboard.stripe.com/settings/ios_certificates) no Dashboard, clique em **Adicionar novo aplicativo** e siga o guia.
Baixe um arquivo de solicitação de assinatura de certificado (CSR) para obter um certificado seguro da Apple que permite usar o Apple Pay.
Um arquivo CSR deve ser usado para emitir exatamente um certificado. Se você trocar seu ID de comerciante da Apple, acesse as [Configurações de certificado do iOS](https://dashboard.stripe.com/settings/ios_certificates) no Dashboard para obter um novo CSR e certificado.
### Integrar com Xcode
Adicione as funções do Apple Pay ao aplicativo. No Xcode, abra as configurações do projeto, clique na guia **Signing & Capabilities** e adicione o recurso **Apple Pay**. Talvez seja necessário fazer login na sua conta de desenvolvedor. Selecione o ID de comerciante criado anteriormente e o aplicativo já pode aceitar Apple Pay.
Habilitar o recurso Apple Pay no Xcode
### Adicionar Apple Pay
#### Pagamento avulso
Para adicionar Apple Pay à PaymentSheet, defina [applePay](https://stripe.dev/stripe-ios/stripe-paymentsheet/Classes/PaymentSheet/Configuration.html#/s:6Stripe12PaymentSheetC13ConfigurationV8applePayAC05ApplefD0VSgvp) após inicializar `PaymentSheet.Configuration` com seu ID de comerciante Apple e o [código de país da sua empresa](https://dashboard.stripe.com/settings/account).
#### iOS (Swift)
```swift
var configuration = PaymentSheet.Configuration()
configuration.applePay = .init(
merchantId: "merchant.com.your_app_name",
merchantCountryCode: "US"
)
```
#### Pagamentos recorrentes
Para adicionar Apple Pay à PaymentSheet, defina [applePay](https://stripe.dev/stripe-ios/stripe-paymentsheet/Classes/PaymentSheet/Configuration.html#/s:6Stripe12PaymentSheetC13ConfigurationV8applePayAC05ApplefD0VSgvp) após inicializar `PaymentSheet.Configuration` com seu ID de comerciante Apple e o [código de país da sua empresa](https://dashboard.stripe.com/settings/account).
De acordo com as [diretrizes da Apple](https://developer.apple.com/design/human-interface-guidelines/apple-pay#Supporting-subscriptions) para pagamentos recorrentes, você também precisará definir atributos adicionais no `PKPaymentRequest`. Adicione um gerenciador em [ApplePayConfiguration.paymentRequestHandlers](https://stripe.dev/stripe-ios/stripepaymentsheet/documentation/stripepaymentsheet/paymentsheet/applepayconfiguration/handlers/paymentrequesthandler) para configurar [PKPaymentRequest.paymentSummaryItems](https://developer.apple.com/documentation/passkit/pkpaymentrequest/1619231-paymentsummaryitems) com o valor que você pretende cobrar (por exemplo, 9,95 USD por mês).
Você também pode adotar [tokens de comerciante](https://developer.apple.com/apple-pay/merchant-tokens/) definindo as propriedades `recurringPaymentRequest` ou `automaticReloadPaymentRequest` no `PKPaymentRequest`.
Para saber mais sobre como usar pagamentos recorrentes com o Apple Pay, consulte a [documentação do PassKit da Apple](https://developer.apple.com/documentation/passkit/pkpaymentrequest).
#### iOS (Swift)
```swift
let customHandlers = PaymentSheet.ApplePayConfiguration.Handlers(
paymentRequestHandler: { request in
// PKRecurringPaymentSummaryItem is available on iOS 15 or later
if #available(iOS 15.0, *) {
let billing = PKRecurringPaymentSummaryItem(label: "My Subscription", amount: NSDecimalNumber(string: "59.99"))
// Payment starts today
billing.startDate = Date()
// Payment ends in one year
billing.endDate = Date().addingTimeInterval(60 * 60 * 24 * 365)
// Pay once a month.
billing.intervalUnit = .month
billing.intervalCount = 1
// recurringPaymentRequest is only available on iOS 16 or later
if #available(iOS 16.0, *) {
request.recurringPaymentRequest = PKRecurringPaymentRequest(paymentDescription: "Recurring",
regularBilling: billing,
managementURL: URL(string: "https://my-backend.example.com/customer-portal")!)
request.recurringPaymentRequest?.billingAgreement = "You'll be billed $59.99 every month for the next 12 months. To cancel at any time, go to Account and click 'Cancel Membership.'"
}
request.paymentSummaryItems = [billing]
request.currencyCode = "USD"
} else {
// On older iOS versions, set alternative summary items.
request.paymentSummaryItems = [PKPaymentSummaryItem(label: "Monthly plan starting July 1, 2022", amount: NSDecimalNumber(string: "59.99"), type: .final)]
}
return request
}
)
var configuration = PaymentSheet.Configuration()
configuration.applePay = .init(merchantId: "merchant.com.your_app_name",
merchantCountryCode: "US",
customHandlers: customHandlers)
```
### Rastreamento de pedidos
Para adicionar informações de [rastreamento de pedidos](https://developer.apple.com/design/human-interface-guidelines/technologies/wallet/designing-order-tracking) no iOS 16 ou posterior, configure um [authorizationResultHandler](https://stripe.dev/stripe-ios/stripepaymentsheet/documentation/stripepaymentsheet/paymentsheet/applepayconfiguration/handlers/authorizationresulthandler) em seu `PaymentSheet.ApplePayConfiguration.Handlers`. A Stripe invoca sua implementação após a conclusão do pagamento, mas antes que o iOS descarte a descrição Apple Pay.
Na sua implementação de `authorizationResultHandler`, obtenha os detalhes do pedido a partir do seu servidor para o pedido concluído. Adicione esses detalhes ao [PKPaymentAuthorizationResult](https://developer.apple.com/documentation/passkit/pkpaymentauthorizationresult) fornecido e retorne o resultado modificado.
Para saber mais sobre o rastreamento de pedidos, consulte a [documentação de pedidos da carteira da Apple](https://developer.apple.com/documentation/walletorders).
#### iOS (Swift)
```swift
let customHandlers = PaymentSheet.ApplePayConfiguration.Handlers(
authorizationResultHandler: { result in
do {
// Fetch the order details from your service
let myOrderDetails = try await MyAPIClient.shared.fetchOrderDetails(orderID: orderID)
result.orderDetails = PKPaymentOrderDetails(
orderTypeIdentifier: myOrderDetails.orderTypeIdentifier, // "com.myapp.order"
orderIdentifier: myOrderDetails.orderIdentifier, // "ABC123-AAAA-1111"
webServiceURL: myOrderDetails.webServiceURL, // "https://my-backend.example.com/apple-order-tracking-backend"
authenticationToken: myOrderDetails.authenticationToken) // "abc123"
// Return your modified PKPaymentAuthorizationResult
return result
} catch {
return PKPaymentAuthorizationResult(status: .failure, errors: [error])
}
}
)
var configuration = PaymentSheet.Configuration()
configuration.applePay = .init(merchantId: "merchant.com.your_app_name",
merchantCountryCode: "US",
customHandlers: customHandlers)
```
## Optional: Personalizar a descrição
Toda personalização é configurada usando o objeto [PaymentSheet.Configuration](https://stripe.dev/stripe-ios/stripe-paymentsheet/Classes/PaymentSheet/Configuration.html).
### Aparência
Customize colors, fonts, and so on to match the look and feel of your app by using the [appearance API](https://docs.stripe.com/elements/appearance-api/mobile.md?platform=ios).
### Layout da forma de pagamento
Configure o layout das formas de pagamento na planilha usando [paymentMethodLayout](https://stripe.dev/stripe-ios/stripepaymentsheet/documentation/stripepaymentsheet/paymentsheet/configuration-swift.struct/paymentmethodlayout). Você pode exibi-los horizontalmente, verticalmente ou deixar a Stripe otimizar o layout automaticamente.
#### Swift
```swift
var configuration = PaymentSheet.Configuration()
configuration.paymentMethodLayout = .automatic
```
### Coletar endereços de usuários
Colete endereços de entrega ou cobrança locais e internacionais de seus clientes usando o [Address Element](https://docs.stripe.com/elements/address-element.md?platform=ios).
### Nome de exibição do comerciante
Especifique o nome da empresa exibido para o cliente definindo [merchantDisplayName](https://stripe.dev/stripe-ios/stripe-paymentsheet/Classes/PaymentSheet/Configuration.html#/s:18StripePaymentSheet0bC0C13ConfigurationV19merchantDisplayNameSSvp). Por padrão, esse é o nome do seu aplicativo.
#### Swift
```swift
var configuration = PaymentSheet.Configuration()
configuration.merchantDisplayName = "My app, Inc."
```
### Modo escuro
A `PaymentSheet` se adapta automaticamente às configurações de aparência do sistema do usuário (modos claro e escuro). Se o seu aplicativo não aceitar o modo escuro, defina [estilo](https://stripe.dev/stripe-ios/stripe-paymentsheet/Classes/PaymentSheet/Configuration.html#/s:18StripePaymentSheet0bC0C13ConfigurationV5styleAC18UserInterfaceStyleOvp) como modo `alwaysLight` ou `alwaysDark`.
```swift
var configuration = PaymentSheet.Configuration()
configuration.style = .alwaysLight
```
### Dados de faturamento padrão
Para definir valores padrão para dados de faturamento coletados na descrição da compra, configure a propriedade `defaultBillingDetails`. A `PaymentSheet` preenche previamente seus campos com os valores que você informou.
```swift
var configuration = PaymentSheet.Configuration()
configuration.defaultBillingDetails.address.country = "US"
configuration.defaultBillingDetails.email = "foo@bar.com"
```
### Coleta de dados de faturamento
Use `billingDetailsCollectionConfiguration` para especificar como você deseja coletar dados de faturamento na página de pagamento.
Você pode coletar o nome, e-mail, número de telefone e endereço do cliente.
Se você quiser apenas os dados de faturamento exigidos pela forma de pagamento, defina `billingDetailsCollectionConfiguration.attachDefaultsToPaymentMethod` como verdadeiro. Nesse caso, `PaymentSheet.Configuration.defaultBillingDetails` são definidos como os [detalhes de faturamento](https://docs.stripe.com/api/payment_methods/object.md?lang=node#payment_method_object-billing_details) da forma de pagamento.
Se você quiser coletar dados de faturamento adicionais que não são necessariamente exigidos pela forma de pagamento, defina `billingDetailsCollectionConfiguration.attachDefaultsToPaymentMethod` como falso. Nesse caso, os dados de faturamento coletados por meio da `PaymentSheet` são definidos como os dados de faturamento da forma de pagamento.
```swift
var configuration = PaymentSheet.Configuration()
configuration.defaultBillingDetails.email = "foo@bar.com"
configuration.billingDetailsCollectionConfiguration.name = .always
configuration.billingDetailsCollectionConfiguration.email = .never
configuration.billingDetailsCollectionConfiguration.address = .full
configuration.billingDetailsCollectionConfiguration.attachDefaultsToPaymentMethod = true
```
> Consulte seu jurídico sobre as leis que se aplicam à coleta de dados. Só colete números de telefone se precisar deles para a transação.
## Optional: Conclua o pagamento em sua IU
Você pode exibir o Payment Sheet apenas para coletar dados da forma de pagamento e depois chamar um método `confirm` para concluir o pagamento na IU do aplicativo. Isso é útil quando você tem um botão de compra personalizado ou precisa de mais etapas após a coleta dos dados do pagamento.
Conclua o pagamento na IU do aplicativo
#### UIKit
As etapas a seguir mostram como concluir o pagamento na IU do aplicativo. Veja nosso exemplo de integração no [GitHub](https://github.com/stripe/stripe-ios/blob/master/Example/PaymentSheet%20Example/PaymentSheet%20Example/ExampleCustomCheckoutViewController.swift).
1. Primeiro, inicialize [PaymentSheet.FlowController](https://stripe.dev/stripe-ios/stripepaymentsheet/documentation/stripepaymentsheet/paymentsheet/flowcontroller) em vez de `PaymentSheet` e atualize a IU com sua propriedade `paymentOption`. Essa propriedade contém uma imagem e um rótulo que representam a forma de pagamento padrão selecionada inicialmente pelo cliente.
```swift
PaymentSheet.FlowController.create(paymentIntentClientSecret: paymentIntentClientSecret, configuration: configuration) { [weak self] result in
switch result {
case .failure(let error):
print(error)
case .success(let paymentSheetFlowController):
self?.paymentSheetFlowController = paymentSheetFlowController
// Update your UI using paymentSheetFlowController.paymentOption
}
}
```
1. Em seguida, chame `presentPaymentOptions` para coletar os detalhes do pagamento. Quando terminar, atualize sua IU novamente com a propriedade `paymentOption`.
```swift
paymentSheetFlowController.presentPaymentOptions(from: self) {
// Update your UI using paymentSheetFlowController.paymentOption
}
```
1. Por fim, chame `confirm`.
```swift
paymentSheetFlowController.confirm(from: self) { paymentResult in
// MARK: Handle the payment result
switch paymentResult {
case .completed:
print("Payment complete!")
case .canceled:
print("Canceled!")
case .failed(let error):
print(error)
}
}
```
#### SwiftUI
As etapas a seguir mostram como concluir o pagamento na IU do aplicativo. Veja nosso exemplo de integração no [GitHub](https://github.com/stripe/stripe-ios/blob/master/Example/PaymentSheet%20Example/PaymentSheet%20Example/ExampleSwiftUICustomPaymentFlow.swift).
1. Primeiro, inicialize [PaymentSheet.FlowController](https://stripe.dev/stripe-ios/stripepaymentsheet/documentation/stripepaymentsheet/paymentsheet/flowcontroller) em vez de `PaymentSheet`. A propriedade `paymentOption` contém uma imagem e um rótulo representando a forma de pagamento selecionada no momento pelo cliente, que você pode usar na sua IU.
```swift
PaymentSheet.FlowController.create(paymentIntentClientSecret: paymentIntentClientSecret, configuration: configuration) { [weak self] result in
switch result {
case .failure(let error):
print(error)
case .success(let paymentSheetFlowController):
self?.paymentSheetFlowController = paymentSheetFlowController
// Use the paymentSheetFlowController.paymentOption properties in your UI
myPaymentMethodLabel = paymentSheetFlowController.paymentOption?.label ?? "Select a payment method"
myPaymentMethodImage = paymentSheetFlowController.paymentOption?.image ?? UIImage(systemName: "square.and.pencil")!
}
}
```
1. Use [PaymentSheet.FlowController.PaymentOptionsButton](https://stripe.dev/stripe-ios/stripepaymentsheet/documentation/stripepaymentsheet/paymentsheet/flowcontroller/paymentoptionsbutton) para inserir o botão que apresenta a descrição da compra para coletar os dados de pagamento. Quando `PaymentSheet.FlowController` chama o argumento `onSheetDismissed`, o `paymentOption` da instância `PaymentSheet.FlowController` reflete a forma de pagamento selecionada.
```swift
PaymentSheet.FlowController.PaymentOptionsButton(
paymentSheetFlowController: paymentSheetFlowController,
onSheetDismissed: {
myPaymentMethodLabel = paymentSheetFlowController.paymentOption?.label ?? "Select a payment method"
myPaymentMethodImage = paymentSheetFlowController.paymentOption?.image ?? UIImage(systemName: "square.and.pencil")!
},
content: {
/* An example button */
HStack {
Text(myPaymentMethodLabel)
Image(uiImage: myPaymentMethodImage)
}
}
)
```
1. Use [PaymentSheet.FlowController.PaymentOptionsButton](https://stripe.dev/stripe-ios/stripepaymentsheet/documentation/stripepaymentsheet/paymentsheet/flowcontroller/paymentoptionsbutton) para encapsular o botão que confirma o pagamento.
```swift
PaymentSheet.FlowController.ConfirmButton(
paymentSheetFlowController: paymentSheetFlowController,
onCompletion: { result in
// MARK: Handle the payment result
switch result {
case .completed:
print("Payment complete!")
case .canceled:
print("Canceled!")
case .failed(let error):
print(error)
}
},
content: {
/* An example button */
Text("Pay")
}
)
```
Se `PaymentSheetResult` for `.completed`, informe ao usuário (por exemplo, exibindo uma tela de confirmação de pedido).
Configurar `allowsDelayedPaymentMethods` como verdadeiro permite formas de pagamento de [notificação assíncrona](https://docs.stripe.com/payments/payment-methods.md#payment-notification) como contas bancárias dos EUA. Para essas formas de pagamento, o status final do pagamento não é conhecido quando o `PaymentSheet` é concluído, sendo efetivado ou não posteriormente. Se você aceitar esses tipos de formas de pagamento, informe o cliente que seu pedido está confirmado e somente processe o pedido (por exemplo, fazendo o envio do produto) quando o pagamento for bem-sucedido.
## Optional: Habilitar formas de pagamento adicionais
Navegue para [Gerenciar formas de pagamento para suas contas conectadas](https://dashboard.stripe.com/settings/payment_methods/connected_accounts) no Dashboard para configurar quais formas de pagamento suas contas conectadas aceitam. As alterações nas configurações padrão se aplicam a todas as contas conectadas novas e existentes.
Consulte os seguintes recursos para obter informações sobre formas de pagamento:
- [Um guia de formas de pagamento](https://stripe.com/payments/payment-methods-guide#choosing-the-right-payment-methods-for-your-business) para ajudar você a escolher as formas de pagamento corretas para sua plataforma.
- [Funções da conta](https://docs.stripe.com/connect/account-capabilities.md) para assegurar que as formas de pagamento escolhidas funcionem para suas contas conectadas.
- Tabelas de [suporte a formas de pagamento e produtos](https://docs.stripe.com/payments/payment-methods/payment-method-support.md#product-support) para assegurar que suas formas de pagamento escolhidas funcionem para seus produtos da Stripe e fluxos de pagamento.
Para cada forma de pagamento, você pode selecionar uma das seguintes opções no menu suspenso:
| |
| |
| **Ativadas por padrão** | Suas contas conectadas aceitam esta forma de pagamento durante o checkout. Algumas formas de pagamento podem ser desativadas ou bloqueadas. Isso ocorre porque suas contas conectadas com *acesso ao Stripe Dashboard* (Platforms can provide connected accounts with access to the full Stripe Dashboard or the Express Dashboard. Otherwise, platforms build an interface for connected accounts using embedded components or the Stripe API) precisam ativá-las em sua página de configurações. |
| **Desativadas por padrão** | Suas contas conectadas não aceitam esta forma de pagamento durante o checkout. Se você permitir que contas conectadas com *acessem o Stripe Dashboard* (Platforms can provide connected accounts with access to the full Stripe Dashboard or the Express Dashboard. Otherwise, platforms build an interface for connected accounts using embedded components or the Stripe API) para gerenciar suas próprias formas de pagamento, elas podem ativar esse recurso. |
| **Bloqueadas** | Suas contas conectadas não aceitam esta forma de pagamento durante o checkout. Se você permitir que contas conectadas com *acessem o Stripe Dashboard* (Platforms can provide connected accounts with access to the full Stripe Dashboard or the Express Dashboard. Otherwise, platforms build an interface for connected accounts using embedded components or the Stripe API) para gerenciar suas próprias formas de pagamento, elas não têm a opção para ativar esse recurso. |
Opções de formas de pagamento
Se fizer uma alteração em uma forma de pagamento, você deve clicar em **Revisar alterações** na barra inferior da tela e em **Salvar e aplicar** para atualizar suas contas conectadas.
Salvar diálogo
### Permitir que contas conectadas gerenciem formas de pagamento
A Stripe recomenda permitir que as contas conectadas personalizem suas próprias formas de pagamento. Esta opção permite que cada conta conectada com *acesso ao Stripe Dashboard* (Platforms can provide connected accounts with access to the full Stripe Dashboard or the Express Dashboard. Otherwise, platforms build an interface for connected accounts using embedded components or the Stripe API) para ver e atualizar sua página de [formas de pagamento](https://dashboard.stripe.com/settings/payment_methods). Somente os proprietários das contas conectadas podem personalizar as formas de pagamento. O Stripe Dashboard exibe o conjunto de padrões de forma de pagamento que você aplicou a todas as contas conectadas novas e existentes. Suas contas conectadas podem sobrepor esses padrões, excluindo as formas de pagamento que você bloqueou.
Marque a caixa de seleção **Personalização da conta** para habilitar essa opção. Você deve clicar em **Revisar alterações** na barra inferior da tela e selecionar **Salvar e aplicar** para atualizar essa configuração.
Caixa de seleção de personalização da conta
### Funções das formas de pagamento
Para permitir que suas contas conectadas aceitem formas de pagamento adicionais, suas `Accounts` devem ter recursos de formas de pagamento ativas.
Se você selecionou a opção “On by default” (ativado por padrão) como método de pagamento em[Gerencie formas de pagamento para suas contas conectadas](https://dashboard.stripe.com/settings/payment_methods/connected_accounts), a Stripe solicita automaticamente a funcionalidade necessário para contas conectadas novas e existentes, caso atendam aos requisitos de verificação. Se a conta conectada não atender aos requisitos ou se você quiser ter controle direto, pode solicitação manualmente a funcionalidade no Dashboard ou na API.
A maioria das formas de pagamento possui os mesmos requisitos de verificação que a funcionalidade `card_payments`, com algumas restrições e exceções. A[tabela de formas de pagamento](https://docs.stripe.com/connect/account-capabilities.md#payment-methods) lista os métodos de pagamento que requerem verificação adicional.
#### Dashboard
[Encontre uma conta conectada](https://docs.stripe.com/connect/dashboard/managing-individual-accounts.md#finding-accounts) no Dashboard para editar suas capacidades e visualizar os requisitos de verificação pendentes.
#### API
Para uma conta conectada existente, você pode [listar](https://docs.stripe.com/api/capabilities/list.md) as funções existentes decidir se precisa solicitar funções adicionais.
```curl
curl https://api.stripe.com/v1/accounts/{{CONNECTEDACCOUNT_ID}}/capabilities \
-u "<>:"
```
Solicite funções adicionais [atualizando](https://docs.stripe.com/api/capabilities/update.md) as funções de cada conta conectada.
```curl
curl https://api.stripe.com/v1/accounts/{{CONNECTEDACCOUNT_ID}}/capabilities/us_bank_account_ach_payments \
-u "<>:" \
-d requested=true
```
Pode haver um atraso antes que a função solicitada se torne ativa. Se a função tiver algum requisito de ativação, ele será incluído nas matrizes de `requirements`.
## Coletar tarifas
Como plataforma, você pode cobrar de suas contas conectadas uma parte de cada transação na forma de tarifas da plataforma. Você pode definir a tarifa da plataforma das seguintes maneiras:
- Use a [ferramenta de preços da plataforma](https://docs.stripe.com/connect/platform-pricing-tools.md) para definir e testar regras de preços. No momento, esse recurso no-code no Stripe Dashboard só está disponível para plataformas responsáveis pelo pagamento das tarifas da Stripe.
- Especifique tarifas de aplicação diretamente em um [PaymentIntent](https://docs.stripe.com/api/payment_intents/object.md). As tarifas definidas com esse método substituem a lógica de precificação especificada na Platform Pricing Tool.
Sua plataforma pode cobrar uma tarifa da plataforma com as seguintes limitações:
- O valor de `application_fee_amount` deve ser positivo e inferior ao o valor da cobrança. A tarifa da plataforma recolhida é limitada ao valor capturado da cobrança.
- Não há tarifas adicionais da Stripe sobre a própria tarifa da plataforma.
- Em conformidade com os requisitos regulatórios e de conformidade do Brasil, plataformas sediadas fora do Brasil com contas conectadas brasileiras não podem recolher tarifas da plataforma por meio da Stripe.
- A moeda de `application_fee_amount` depende de alguns fatores de [várias moedas](https://docs.stripe.com/connect/currencies.md).
A [BalanceTransaction](https://docs.stripe.com/api.md#balance_transaction_retrieve) da cobrança resultante inclui um detalhamento das tarifas, tanto da Stripe quanto das tarifas da plataforma. Para proporcionar uma melhor experiência de relatórios, a cobrança de uma tarifa gera um objeto [ApplicationFee](https://docs.stripe.com/api/application_fees/object.md). Use a propriedade `amount`t no objeto `ApplicationFee` para fins de relatório.
Você pode visualizar as tarifas da plataforma na seção [tarifas cobradas](https://dashboard.stripe.com/connect/application_fees) do Dashboard.
> Por padrão, as tarifas da plataforma para cobranças diretas são criadas de forma assíncrona. Se você expandir o objeto `application_fee` em uma solicitação de criação de cobrança, a tarifa da plataforma será criada de forma síncrona como parte dessa solicitação. Somente expanda o objeto `application_fee` se for necessário, pois isso aumenta a latência da solicitação.
>
> Para receber notificações de objetos `ApplicationFee` criados de forma assíncrona, escute o evento de Webhook [application_fee.created](https://docs.stripe.com/api/events/types.md#event_types-application_fee.created).
Integre a IU de pagamento incorporada da Stripe no checkout do seu aplicativo Android com a classe [PaymentSheet](https://stripe.dev/stripe-android/paymentsheet/com.stripe.android.paymentsheet/-payment-sheet/index.html).
## Configurar a Stripe [Lado do servidor] [Lado do cliente]
Primeiro, você precisa de uma conta Stripe. [Cadastre-se agora](https://dashboard.stripe.com/register).
### Lado do servidor
Esta integração exige que os endpoints do seu servidor se comuniquem com a API da Stripe. Use as bibliotecas oficiais para acessar a API da Stripe pelo seu servidor:
#### 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'
```
### Lado do cliente
O [SDK da Stripe para Android](https://github.com/stripe/stripe-android) é de código aberto e [totalmente documentado](https://stripe.dev/stripe-android/).
Para instalar o SDK, adicione `stripe-android` ao bloco `dependencies` do arquivo [app/build.gradle](https://developer.android.com/studio/build/dependencies):
#### Kotlin
```kotlin
plugins {
id("com.android.application")
}
android { ... }
dependencies {
// ...
// Stripe Android SDK
implementation("com.stripe:stripe-android:23.0.2")
// Include the financial connections SDK to support US bank account as a payment method
implementation("com.stripe:financial-connections:23.0.2")
}
```
> Veja mais informações sobre o último lançamento de SDK e as versões anteriores na página [Lançamentos](https://github.com/stripe/stripe-android/releases) no GitHub. Para receber notificações quando um novo lançamento for publicado, [assista aos lançamentos do repositório](https://docs.github.com/en/github/managing-subscriptions-and-notifications-on-github/configuring-notifications#configuring-your-watch-settings-for-an-individual-repository).
Configure o SDK com sua [chave publicável](https://dashboard.stripe.com/apikeys) da Stripe, de modo que seja possível fazer solicitações à API Stripe, como em sua subcategoria `Application`:
#### Kotlin
```kotlin
import com.stripe.android.PaymentConfiguration
class MyApp : Application() {
override fun onCreate() {
super.onCreate()
PaymentConfiguration.init(
applicationContext,
"<>"
)
}
}
```
> Use suas [chaves de teste](https://docs.stripe.com/keys.md#obtain-api-keys) enquanto testa e desenvolve, e suas chaves de [modo de produção](https://docs.stripe.com/keys.md#test-live-modes) quando publicar seu aplicativo.
## Adicionar um endpoint [Lado do servidor]
> #### Nota
>
> Para exibir o PaymentSheet antes de criar um PaymentIntent, consulte [Colete os dados de pagamento antes de criar um Intent](https://docs.stripe.com/payments/accept-a-payment-deferred.md?type=payment).
Se a sua plataforma Connect utiliza [Contas configuradas pelo cliente](https://docs.stripe.com/api/v2/core/accounts/create.md#v2_create_accounts-configuration-customer), utilize o nosso [guia](https://docs.stripe.com/connect/use-accounts-as-customers.md) para substituir as referências a `Cliente` e eventos no seu código pelas referências equivalentes da API Accounts v2.
Esta integração usa três objetos da API da Stripe:
1. [PaymentIntent](https://docs.stripe.com/api/payment_intents.md): A Stripe usa isso para representar sua intenção de coletar o pagamento de um cliente, acompanhando suas tentativas de cobrança e alterações no estado do pagamento durante todo o processo.
1. (Opcional) [Customer](https://docs.stripe.com/api/customers.md): Para configurar uma forma de pagamento para pagamentos futuros, vincule-a a um *Customer* (Customer objects represent customers of your business. They let you reuse payment methods and give you the ability to track multiple payments). Crie um objeto Customer quando o cliente abrir uma conta na sua empresa. Se o cliente pagar como convidado, você pode criar o objeto Customer antes do pagamento e associá-lo à sua representação interna da conta do cliente, mais tarde.
1. (Opcional) [CustomerSession](https://docs.stripe.com/api/customer_sessions.md): Os dados do objeto Customer são confidenciais e não podem ser recuperados diretamente do aplicativo. Uma CustomerSession concede ao SDK acesso temporário com escopo definido ao cliente e fornece opções de configuração adicionais. Consulte uma lista completa de [opções de configuração](https://docs.stripe.com/api/customer_sessions/create.md#create_customer_session-components).
> Se você nunca salva cartões para um cliente e não permite que clientes retornando reutilizem cartões salvos, é possível omitir os objetos cliente e CustomerSession da sua integração.
Por motivos de segurança, o aplicativo não pode criar esses objetos. Para isso, adicione um endpoint ao servidor para:
1. Recuperar ou criar um Customer.
1. Cria uma [CustomerSession](https://docs.stripe.com/api/customer_sessions.md) para o cliente.
1. Cria um PaymentIntent com o [valor](https://docs.stripe.com/api/payment_intents/create.md#create_payment_intent-amount), a [moeda](https://docs.stripe.com/api/payment_intents/create.md#create_payment_intent-currency) e o [cliente](https://docs.stripe.com/api/payment_intents/create.md#create_payment_intent-customer).
1. Retorna o *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)) do Payment Intent, o `client_secret` da CustomerSession, o [id](https://docs.stripe.com/api/customers/object.md#customer_object-id) do Cliente e sua [chave publicável](https://dashboard.stripe.com/apikeys) para seu aplicativo.
As formas de pagamento mostradas aos clientes durante o processo de checkout também são incluídas no PaymentIntent. Você pode permitir que a Stripe obtenha as formas de pagamento das configurações do Dashboard ou listá-las manualmente. Independentemente da opção escolhida, saiba que a moeda passada no PaymentIntent filtra as formas de pagamento mostradas para o cliente. Por exemplo, se você passar EUR no `eur` e a OXXO estiver ativada no Dashboard, a OXXO não será exibida ao cliente porque a OXXO não aceita pagamentos em `eur`.
Se sua integração não exige uma opção baseada em código para oferecer formas de pagamento, a Stripe recomenda a opção automática. Isso ocorre porque a Stripe avalia a moeda, as restrições de forma de pagamento e outros parâmetros para determinar a lista de formas de pagamento aceitas. Priorizamos as formas de formas de pagamento que aumentam a conversão e que são mais relevantes para a moeda e a localização do cliente.
#### Gerenciar formas de pagamento no Dashboard
Você pode gerenciar formas de pagamento no [Dashboard](https://dashboard.stripe.com/settings/payment_methods). A Stripe processa a devolução de formas de pagamento qualificadas com base em fatores como valor, moeda e fluxo de pagamento da transação. O PaymentIntent é criado usando as formas de pagamento configuradas no Dashboard. Se não quiser usar o Dashboard ou se quiser especificar formas de pagamento manualmente, você pode listá-las usando o atributo `payment_method_types`.
#### curl
```bash
# Create a Customer (use an existing Customer ID if this is a returning customer)
curl https://api.stripe.com/v1/customers \
-u <>: \
-X "POST" \
-H "Stripe-Account: {{CONNECTED_ACCOUNT_ID}}"
# Create an CustomerSession for the Customer
curl https://api.stripe.com/v1/customer_sessions \
-u <>: \
-X "POST" \
-d "customer"="{{CUSTOMER_ID}}" \
-d "components[mobile_payment_element][enabled]"=true \
-d "components[mobile_payment_element][features][payment_method_save]"=enabled \
-d "components[mobile_payment_element][features][payment_method_redisplay]"=enabled \
-d "components[mobile_payment_element][features][payment_method_remove]"=enabled
# Create a PaymentIntent
curl https://api.stripe.com/v1/payment_intents \
-u <>: \
-H "Stripe-Account: {{CONNECTED_ACCOUNT_ID}}"
-X "POST" \
-d "customer"="{{CUSTOMER_ID}}" \
-d "amount"=1099 \
-d "currency"="eur" \
# In the latest version of the API, specifying the `automatic_payment_methods` parameter
# is optional because Stripe enables its functionality by default.
-d "automatic_payment_methods[enabled]"=true \
-d application_fee_amount="123" \
```
#### Listar manualmente as formas de pagamento
#### curl
```bash
# Create a Customer (use an existing Customer ID if this is a returning customer)
curl https://api.stripe.com/v1/customers \
-u <>: \
-X "POST" \
-H "Stripe-Account: {{CONNECTED_ACCOUNT_ID}}"
# Create an CustomerSession for the Customer
curl https://api.stripe.com/v1/customer_sessions \
-u <>: \
-X "POST" \
-d "customer"="{{CUSTOMER_ID}}" \
-d "components[mobile_payment_element][enabled]"=true \
-d "components[mobile_payment_element][features][payment_method_save]"=enabled \
-d "components[mobile_payment_element][features][payment_method_redisplay]"=enabled \
-d "components[mobile_payment_element][features][payment_method_remove]"=enabled
# Create a PaymentIntent
curl https://api.stripe.com/v1/payment_intents \
-u <>: \
-H "Stripe-Account: {{CONNECTED_ACCOUNT_ID}}"
-X "POST" \
-d "customer"="{{CUSTOMER_ID}}" \
-d "amount"=1099 \
-d "currency"="eur" \
-d "payment_method_types[]"="bancontact" \
-d "payment_method_types[]"="card" \
-d "payment_method_types[]"="ideal" \
-d "payment_method_types[]"="klarna" \
-d "payment_method_types[]"="sepa_debit" \
-d application_fee_amount="123" \
```
> A forma de pagamento precisa aceitar a moeda passada no PaymentIntent. Além disso, sua empresa precisa estar estabelecida em um dos países aceitos pela forma de pagamento. Consulte a página [Opções de integração de formas de pagamento](https://docs.stripe.com/payments/payment-methods/integration-options.md) para obter mais detalhes sobre o que é aceito.
## Integrar a descrição da compra [Lado do cliente]
Antes de exibir o Element Pagamento para dispositivos móveis, a página de checkout deve:
- Mostrar os produtos sendo comprados e o valor total
- Colete todas as informações de envio necessárias usando o [Address Element](https://docs.stripe.com/elements/address-element.md?platform=android)
- Incluir um botão de checkout para apresentar a IU da Stripe
#### Jetpack Compose
[Inicializar](https://stripe.dev/stripe-android/paymentsheet/com.stripe.android.paymentsheet/-payment-sheet/-builder/index.html) uma instância de `PaymentSheet` dentro de `onCreate` da sua atividade de checkout, passando um método para gerenciar o resultado.
```kotlin
import androidx.compose.runtime.Composable
import androidx.compose.runtime.remember
import com.stripe.android.paymentsheet.PaymentSheet
import com.stripe.android.paymentsheet.PaymentSheetResult
@Composable
fun App() {
val paymentSheet = remember { PaymentSheet.Builder(::onPaymentSheetResult) }.build()
}
private fun onPaymentSheetResult(paymentSheetResult: PaymentSheetResult) {
// implemented in the next steps
}
```
Em seguida, busque o segredo do cliente de Intenção Payment, o segredo do cliente da Sessão do cliente, a ID do cliente e a chave publicável do endpoint que você criou na etapa anterior. Defina a chave publicável usando`PaymentConfiguration` e armazene os outros para uso quando apresentar o PaymentSheet.
```kotlin
import androidx.compose.runtime.Composable
import androidx.compose.runtime.rememberimport androidx.compose.runtime.LaunchedEffect
import androidx.compose.runtime.getValue
import androidx.compose.runtime.mutableStateOf
import androidx.compose.runtime.setValue
import androidx.compose.ui.platform.LocalContext
import com.stripe.android.PaymentConfiguration
import com.stripe.android.paymentsheet.PaymentSheet
import com.stripe.android.paymentsheet.PaymentSheetResult
@Composable
fun App() {
val paymentSheet = remember { PaymentSheet.Builder(::onPaymentSheetResult) }.build()val context = LocalContext.current
var customerConfig by remember { mutableStateOf(null) }
varpaymentIntentClientSecret by remember { mutableStateOf(null) }
LaunchedEffect(context) {
// Make a request to your own server and retrieve payment configurations
val networkResult = ...
if (networkResult.isSuccess) {paymentIntentClientSecret = networkResult.paymentIntent
customerConfig = PaymentSheet.CustomerConfiguration.createWithCustomerSession(
id = networkResult.customer,
clientSecret = networkResult.customerSessionClientSecret
)PaymentConfiguration.init(context, networkResult.publishableKey, ""{{CONNECTED_ACCOUNT_ID}}"")}
}
}
private fun onPaymentSheetResult(paymentSheetResult: PaymentSheetResult) {
// implemented in the next steps
}
```
Quando o cliente tocar no botão checkout, chame [presentWithPaymentIntent](https://stripe.dev/stripe-android/paymentsheet/com.stripe.android.paymentsheet/-payment-sheet/index.html#1814490530%2FFunctions%2F2002900378) para apresentar a descrição da compra. Depois que o cliente conclui o pagamento, a descrição é descartada e o [PaymentSheetResultCallback](https://stripe.dev/stripe-android/paymentsheet/com.stripe.android.paymentsheet/-payment-sheet-result-callback/index.html) é chamado com um [PaymentSheetResult](https://stripe.dev/stripe-android/paymentsheet/com.stripe.android.paymentsheet/-payment-sheet-result/index.html).
```kotlin
import androidx.compose.material.Button
import androidx.compose.material.Text
import androidx.compose.runtime.Composable
import androidx.compose.runtime.LaunchedEffect
import androidx.compose.runtime.getValue
import androidx.compose.runtime.mutableStateOf
import androidx.compose.runtime.remember
import androidx.compose.runtime.setValue
import androidx.compose.ui.platform.LocalContext
import com.stripe.android.PaymentConfiguration
import com.stripe.android.paymentsheet.PaymentSheet
import com.stripe.android.paymentsheet.PaymentSheetResult
@Composable
fun App() {
val paymentSheet = remember { PaymentSheet.Builder(::onPaymentSheetResult) }.build()
val context = LocalContext.current
var customerConfig by remember { mutableStateOf(null) }
var paymentIntentClientSecret by remember { mutableStateOf(null) }
LaunchedEffect(context) {
// Make a request to your own server and retrieve payment configurations
val networkResult = ...
if (networkResult.isSuccess) {
paymentIntentClientSecret = networkResult.paymentIntent
customerConfig = PaymentSheet.CustomerConfiguration.createWithCustomerSession(
id = networkResult.customer,
clientSecret = networkResult.customerSessionClientSecret
)
PaymentConfiguration.init(context, networkResult.publishableKey, ""{{CONNECTED_ACCOUNT_ID}}"")
}
}Button(
onClick = {
val currentConfig = customerConfig
val currentClientSecret =paymentIntentClientSecret
if (currentConfig != null && currentClientSecret != null) {
presentPaymentSheet(paymentSheet, currentConfig, currentClientSecret)
}
}
) {
Text("Checkout")
}
}private fun presentPaymentSheet(
paymentSheet: PaymentSheet,
customerConfig: PaymentSheet.CustomerConfiguration,paymentIntentClientSecret: String
) {
paymentSheet.presentWithPaymentIntent(paymentIntentClientSecret,
PaymentSheet.Configuration.Builder(merchantDisplayName = "My merchant name")
.customer(customerConfig)
// Set `allowsDelayedPaymentMethods` to true if your business handles
// delayed notification payment methods like US bank accounts.
.allowsDelayedPaymentMethods(true)
.build()
)
}
private fun onPaymentSheetResult(paymentSheetResult: PaymentSheetResult) {when(paymentSheetResult) {
is PaymentSheetResult.Canceled -> {
print("Canceled")
}
is PaymentSheetResult.Failed -> {
print("Error: ${paymentSheetResult.error}")
}
is PaymentSheetResult.Completed -> {
// Display for example, an order confirmation screen
print("Completed")
}
}
}
```
#### Visualizações (Clássico)
[Inicialize](https://stripe.dev/stripe-android/paymentsheet/com.stripe.android.paymentsheet/-payment-sheet/index.html#-394860221%2FConstructors%2F2002900378) uma instância de `PaymentSheet` dentro de `onCreate` da sua atividade de checkout, passando um método para gerenciar o resultado.
#### Kotlin
```kotlin
import com.stripe.android.paymentsheet.PaymentSheet
class CheckoutActivity : AppCompatActivity() {
lateinit var paymentSheet: PaymentSheet
override fun onCreate(savedInstanceState: Bundle?) {
super.onCreate(savedInstanceState)
paymentSheet = PaymentSheet.Builder(::onPaymentSheetResult).build(this)
}
fun onPaymentSheetResult(paymentSheetResult: PaymentSheetResult) {
// implemented in the next steps
}
}
```
Em seguida, busque o segredo do cliente de Intenção Payment, o segredo do cliente da Sessão do cliente, a ID do cliente e a chave publicável do endpoint que você criou na etapa anterior. Defina a chave publicável usando`PaymentConfiguration` e armazene os outros para uso quando apresentar o PaymentSheet.
#### Kotlin
```kotlin
import com.stripe.android.paymentsheet.PaymentSheet
class CheckoutActivity : AppCompatActivity() {
lateinit var paymentSheet: PaymentSheetlateinit var customerConfig: PaymentSheet.CustomerConfiguration
lateinit varpaymentIntentClientSecret: String
override fun onCreate(savedInstanceState: Bundle?) {
super.onCreate(savedInstanceState)
paymentSheet = PaymentSheet.Builder(::onPaymentSheetResult).build(this)lifecycleScope.launch {
// Make a request to your own server and retrieve payment configurations
val networkResult = MyBackend.getPaymentConfig()
if (networkResult.isSuccess) {paymentIntentClientSecret = networkResult.paymentIntent
customerConfig = PaymentSheet.CustomerConfiguration.createWithCustomerSession(
id = networkResult.customer,
clientSecret = networkResult.customerSessionClientSecret
)PaymentConfiguration.init(context, networkResult.publishableKey, ""{{CONNECTED_ACCOUNT_ID}}"")}
}
}
fun onPaymentSheetResult(paymentSheetResult: PaymentSheetResult) {
// implemented in the next steps
}
}
```
Quando o cliente tocar no botão checkout, chame [presentWithPaymentIntent](https://stripe.dev/stripe-android/paymentsheet/com.stripe.android.paymentsheet/-payment-sheet/index.html#1814490530%2FFunctions%2F2002900378) para apresentar a descrição da compra. Depois que o cliente conclui o pagamento, a descrição é descartada e o [PaymentSheetResultCallback](https://stripe.dev/stripe-android/paymentsheet/com.stripe.android.paymentsheet/-payment-sheet-result-callback/index.html) é chamado com um [PaymentSheetResult](https://stripe.dev/stripe-android/paymentsheet/com.stripe.android.paymentsheet/-payment-sheet-result/index.html).
#### Kotlin
```kotlin
// ...
class CheckoutActivity : AppCompatActivity() {
lateinit var paymentSheet: PaymentSheet
lateinit var customerConfig: PaymentSheet.CustomerConfiguration
lateinit var paymentIntentClientSecret: String
// ...fun presentPaymentSheet() {
paymentSheet.presentWithPaymentIntent(paymentIntentClientSecret,
PaymentSheet.Configuration.Builder(merchantDisplayName = "My merchant name")
.customer(customerConfig)
// Set `allowsDelayedPaymentMethods` to true if your business handles
// delayed notification payment methods like US bank accounts.
.allowsDelayedPaymentMethods(true)
.build()
)
}
fun onPaymentSheetResult(paymentSheetResult: PaymentSheetResult) {when(paymentSheetResult) {
is PaymentSheetResult.Canceled -> {
print("Canceled")
}
is PaymentSheetResult.Failed -> {
print("Error: ${paymentSheetResult.error}")
}
is PaymentSheetResult.Completed -> {
// Display for example, an order confirmation screen
print("Completed")
}
}
}
}
```
Configurar `allowsDelayedPaymentMethods` como verdadeiro permite formas de pagamento de [notificação assíncrona](https://docs.stripe.com/payments/payment-methods.md#payment-notification) como contas bancárias dos EUA. Para essas formas de pagamento, o status final do pagamento não é conhecido quando o `PaymentSheet` é concluído, sendo efetivado ou não posteriormente. Se você aceitar esses tipos de formas de pagamento, informe o cliente que seu pedido está confirmado e somente processe o pedido (por exemplo, fazendo o envio do produto) quando o pagamento for bem-sucedido.
## Gerenciar eventos pós-pagamento [Lado do servidor]
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 a [ferramenta Dashboard webhook](https://dashboard.stripe.com/webhooks) ou siga o [guia de webhooks](https://docs.stripe.com/webhooks/quickstart.md) para receber esses eventos e executar ações, como enviar um e-mail de confirmação do pedido ao cliente, registrar a venda em um banco de dados ou iniciar um fluxo de trabalho de envio.
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 sua integração para escutar eventos assíncronos é o que permite a você aceitar [diferentes tipos de formas de pagamento](https://stripe.com/payments/payment-methods-guide) com uma única integração.
Além de gerenciar o evento `payment_intent.succeeded`, recomendamos gerenciar esses outros eventos ao coletar pagamentos com o Element Pagamento:
| Evento | Descrição | Ação |
| ------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [payment_intent.succeeded](https://docs.stripe.com/api/events/types.md?lang=php#event_types-payment_intent.succeeded) | Enviado quando um cliente conclui um pagamento com êxito. | Envie ao cliente uma confirmação de pedido e *processe* (Fulfillment is the process of providing the goods or services purchased by a customer, typically after payment is collected) o pedido. |
| [payment_intent.processing](https://docs.stripe.com/api/events/types.md?lang=php#event_types-payment_intent.processing) | Enviado quando um cliente inicia um pagamento, mas o pagamento ainda precisa ser concluído. Esse evento costuma ser enviado quando um cliente inicia um débito bancário. Ele é seguido por um evento `payment_intent.succeeded` ou `payment_intent.payment_failed` no futuro. | Envie ao cliente uma confirmação do pedido que indica que o pagamento está pendente. Para produtos digitais, pode ser necessário executar o pedido antes de aguardar a conclusão do pagamento. |
| [payment_intent.payment_failed](https://docs.stripe.com/api/events/types.md?lang=php#event_types-payment_intent.payment_failed) | Enviado quando um cliente tenta fazer um pagamento, mas o pagamento falha. | Se um pagamento passa de `processing` para `payment_failed`, ofereça ao cliente outra tentativa para pagar. |
## Testar a integração
#### Cartões
| Número do cartão | Cenário | Como testar |
| ------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------- |
| 4242424242424242 | O pagamento com cartão é bem-sucedido e não precisa de autenticação. | Preencha o formulário do cartão de crédito usando o número do cartão de crédito com qualquer validade, CVC e código postal. |
| 4000002500003155 | O pagamento com cartão precisa de *autenticação* (Strong Customer Authentication (SCA) is a regulatory requirement in effect as of September 14, 2019, that impacts many European online payments. It requires customers to use two-factor authentication like 3D Secure to verify their purchase). | Preencha o formulário do cartão de crédito usando o número do cartão de crédito com qualquer validade, CVC e código postal. |
| 4000000000009995 | O cartão é recusado com um código de recusa como `insufficient_funds`. | Preencha o formulário do cartão de crédito usando o número do cartão de crédito com qualquer validade, CVC e código postal. |
| 6205500000000000004 | O cartão UnionPay tem um comprimento variável de 13 a 19 dígitos. | Preencha o formulário do cartão de crédito usando o número do cartão de crédito com qualquer validade, CVC e código postal. |
#### Débito bancário autenticado
| Forma de pagamento | Cenário | Como testar |
| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Bancontact, iDEAL | Seu cliente não faz a autenticação na página de redirecionamento de uma forma de pagamento baseada em redirecionamento e notificação imediata. | Escolha qualquer forma de pagamento baseada em redirecionamento, preencha os dados obrigatórios e confirme o pagamento. Em seguida, clique em **Falhar pagamento de teste** na página de redirecionamento. |
| Pay by Bank | O cliente paga com uma forma de pagamento baseada em redirecionamento e [notificação posterior](https://docs.stripe.com/payments/payment-methods.md#payment-notification). | Escolha a forma de pagamento, preencha os dados obrigatórios e confirme o pagamento. Em seguida, clique em **Concluir o pagamento de teste** na página de redirecionamento. |
| Pay by Bank | Seu cliente não faz a autenticação na página de redirecionamento de uma forma de pagamento baseada em redirecionamento e notificação posterior. | Escolha a forma de pagamento, preencha os dados obrigatórios e confirme o pagamento. Em seguida, clique em **Falhar o pagamento de teste** na página de redirecionamento. |
| BLIK | Os pagamentos BLIK falham de várias formas: falhas imediatas (por exemplo, o código está vencido ou inválido), erros atrasados (o banco recusa) ou limites de tempo (o cliente não respondeu a tempo). | Use padrões de e-mail para [simular as diferentes falhas.](https://docs.stripe.com/payments/blik/accept-a-payment.md#simulate-failures) |
#### Débitos bancários
| Forma de pagamento | Cenário | Como testar |
| ---------------------- | ------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Débito automático SEPA | O cliente paga com débito automático SEPA. | Preencha o formulário usando o número de conta `AT321904300235473204`. Inicialmente, o status do PaymentIntent muda para processando e, três minutos depois, para bem-sucedido. |
| Débito automático SEPA | O status da intenção de pagamento do cliente muda de `processing` para `requires_payment_method`. | Preencha o formulário usando o número de conta `AT861904300235473202`. |
Consulte [Testes](https://docs.stripe.com/testing.md) para obter mais informações sobre como testar sua integração.
## Optional: Ativar Google Pay
### Configurar a integração
Para usar o Google Pay, habilite a API Google Pay adicionando o seguinte à `` tag do seu **AndroidManifest.xml**:
```xml
...
```
Veja mais detalhes na [Configuração da API Google Pay](https://developers.google.com/pay/api/android/guides/setup) do Google Pay para Android.
### Adicionar Google Pay
Para adicionar o Google Pay à sua integração, passe uma [PaymentSheet.GooglePayConfiguration](https://stripe.dev/stripe-android/paymentsheet/com.stripe.android.paymentsheet/-payment-sheet/-google-pay-configuration/index.html) com seu ambiente do Google Pay (produção ou teste) e o [código do país da sua empresa](https://dashboard.stripe.com/settings/account) quando inicializar [PaymentSheet.Configuration](https://stripe.dev/stripe-android/paymentsheet/com.stripe.android.paymentsheet/-payment-sheet/-configuration/index.html).
#### Kotlin
```kotlin
val googlePayConfiguration = PaymentSheet.GooglePayConfiguration(
environment = PaymentSheet.GooglePayConfiguration.Environment.Test,
countryCode = "US",
currencyCode = "USD" // Required for Setup Intents, optional for Payment Intents
)
val configuration = PaymentSheet.Configuration.Builder(merchantDisplayName = "My merchant name")
.googlePay(googlePayConfiguration)
.build()
```
### Testar Google Pay
O Google permite que você faça pagamentos de teste por meio de seu [Pacote de cartão de teste](https://developers.google.com/pay/api/android/guides/resources/test-card-suite). O Pacote de cartão de teste é compatível com os [cartões de teste](https://docs.stripe.com/testing.md) da Stripe.
Você precisa testar o Google Pay usando um dispositivo Android físico em vez de um dispositivo simulado, em um país onde o Google Pay é compatível. Faça login em uma conta do Google em seu dispositivo de teste com um cartão real salvo na Carteira do Google.
## Optional: Personalizar a descrição
Toda personalização é configurada usando o objeto [PaymentSheet.Configuration](https://stripe.dev/stripe-android/paymentsheet/com.stripe.android.paymentsheet/-payment-sheet/-configuration/index.html).
### Aparência
Customize colors, fonts, and more to match the look and feel of your app by using the [appearance API](https://docs.stripe.com/elements/appearance-api/mobile.md?platform=android).
### Layout da forma de pagamento
Configure o layout das formas de pagamento na planilha usando [paymentMethodLayout](https://stripe.dev/stripe-android/paymentsheet/com.stripe.android.paymentsheet/-payment-sheet/-configuration/-builder/index.html#2123253356%2FFunctions%2F2002900378). Você pode exibi-los horizontalmente, verticalmente ou deixar a Stripe otimizar o layout automaticamente.
#### Kotlin
```kotlin
PaymentSheet.Configuration.Builder("Example, Inc.")
.paymentMethodLayout(PaymentSheet.PaymentMethodLayout.Automatic)
.build()
```
### Coletar endereços de usuários
Colete endereços de entrega ou cobrança locais e internacionais de seus clientes usando o [Address Element](https://docs.stripe.com/elements/address-element.md?platform=android).
### Nome de exibição da empresa
Especifique o nome da empresa exibido para o cliente definindo [merchantDisplayName](https://stripe.dev/stripe-android/paymentsheet/com.stripe.android.paymentsheet/-payment-sheet/-configuration/index.html#-191101533%2FProperties%2F2002900378). Por padrão, esse é o nome do seu aplicativo.
#### Kotlin
```kotlin
PaymentSheet.Configuration.Builder(
merchantDisplayName = "My app, Inc."
).build()
```
### Modo escuro
Por padrão, o `PaymentSheet` se adapta automaticamente às configurações de aparência do sistema do usuário (modo claro e escuro). É possível alterar isso configurando modo claro ou escuro no seu aplicativo:
#### Kotlin
```kotlin
// force dark
AppCompatDelegate.setDefaultNightMode(AppCompatDelegate.MODE_NIGHT_YES)
// force light
AppCompatDelegate.setDefaultNightMode(AppCompatDelegate.MODE_NIGHT_NO)
```
### Dados de faturamento padrão
Para definir valores padrão para dados de faturamento coletados na descrição da compra, configure a propriedade `defaultBillingDetails`. A `PaymentSheet` preenche previamente seus campos com os valores que você informou.
#### Kotlin
```kotlin
val address = PaymentSheet.Address(country = "US")
val billingDetails = PaymentSheet.BillingDetails(
address = address,
email = "foo@bar.com"
)
val configuration = PaymentSheet.Configuration.Builder(merchantDisplayName = "Merchant, Inc.")
.defaultBillingDetails(billingDetails)
.build()
```
### Configurar coleta de dados de cobrança
Usar `BillingDetailsCollectionConfiguration` para especificar como você deseja coletar dados de cobrança no PaymentSheet.
Você pode coletar o nome, e-mail, número de telefone e endereço do cliente.
Se quiser anexar detalhes de cobrança padrão ao objeto PaymentMethod mesmo quando esses campos não forem coletados na IU, defina `billingDetailsCollectionConfiguration.attachDefaultsToPaymentMethod` como `true`.
#### Kotlin
```kotlin
val billingDetails = PaymentSheet.BillingDetails(
email = "foo@bar.com"
)
val billingDetailsCollectionConfiguration = BillingDetailsCollectionConfiguration(
attachDefaultsToPaymentMethod = true,
name = BillingDetailsCollectionConfiguration.CollectionMode.Always,
email = BillingDetailsCollectionConfiguration.CollectionMode.Never,
address = BillingDetailsCollectionConfiguration.AddressCollectionMode.Full,
)
val configuration = PaymentSheet.Configuration.Builder(merchantDisplayName = "Merchant, Inc.")
.defaultBillingDetails(billingDetails)
.billingDetailsCollectionConfiguration(billingDetailsCollectionConfiguration)
.build()
```
> Consulte seu jurídico sobre as leis que se aplicam à coleta de dados. Só colete números de telefone se precisar deles para a transação.
## Optional: Conclua o pagamento em sua IU
Você pode exibir a Payment Sheet apenas para coletar dados da forma de pagamento e concluir o pagamento na IU do aplicativo. Isso é útil quando você tem um botão de compra personalizado ou precisa de mais etapas após a coleta dos dados do pagamento.
> Um exemplo de integração está [disponível no nosso GitHub](https://github.com/stripe/stripe-android/blob/master/paymentsheet-example/src/main/java/com/stripe/android/paymentsheet/example/samples/ui/paymentsheet/custom_flow/CustomFlowActivity.kt).
1. Primeiro, inicialize [PaymentSheet.FlowController](https://stripe.dev/stripe-android/paymentsheet/com.stripe.android.paymentsheet/-payment-sheet/-flow-controller/index.html) em vez de `PaymentSheet` usando um dos métodos do [Builder](https://stripe.dev/stripe-android/paymentsheet/com.stripe.android.paymentsheet/-payment-sheet/-flow-controller/-builder/index.html).
#### Android (Kotlin)
```kotlin
class CheckoutActivity : AppCompatActivity() {
private lateinit var flowController: PaymentSheet.FlowController
override fun onCreate(savedInstanceState: Bundle?) {
super.onCreate(savedInstanceState)
val flowController = PaymentSheet.FlowController.Builder(
resultCallback = ::onPaymentSheetResult,
paymentOptionResultCallback = ::onPaymentOption,
).build(this)
}
}
```
1. Em seguida, chame `configureWithPaymentIntent` com as chaves do objeto Stripe recuperadas do backend e atualize a IU no callback usando [getPaymentOption()](https://stripe.dev/stripe-android/paymentsheet/com.stripe.android.paymentsheet/-payment-sheet/-flow-controller/index.html#-2091462043%2FFunctions%2F2002900378). Isso contém uma imagem e um rótulo que representam a forma de pagamento selecionada atualmente pelo cliente.
#### Android (Kotlin)
```kotlin
flowController.configureWithPaymentIntent(
paymentIntentClientSecret = paymentIntentClientSecret,
configuration = PaymentSheet.Configuration.Builder("Example, Inc.")
.customer(PaymentSheet.CustomerConfiguration(
id = customerId,
ephemeralKeySecret = ephemeralKeySecret
))
.build()
) { isReady, error ->
if (isReady) {
// Update your UI using `flowController.getPaymentOption()`
} else {
// handle FlowController configuration failure
}
}
```
1. Em seguida, chame [presentPaymentOptions](https://stripe.dev/stripe-android/paymentsheet/com.stripe.android.paymentsheet/-payment-sheet/-flow-controller/index.html#449924733%2FFunctions%2F2002900378) para coletar os detalhes do pagamento. Quando o cliente termina, a descrição da compra é descartada e chama o [paymentOptionCallback](https://stripe.dev/stripe-android/paymentsheet/com.stripe.android.paymentsheet/-payment-option-callback/index.html) passado anteriormente em `create`. Implemente essa forma para atualizar a IU com o `paymentOption` retornado.
#### Android (Kotlin)
```kotlin
// ...
flowController.presentPaymentOptions()
// ...
private fun onPaymentOption(paymentOptionResult: PaymentOptionResult) {
val paymentOption = paymentOptionResult.paymentOption
if (paymentOption != null) {
paymentMethodButton.text = paymentOption.label
paymentMethodButton.setCompoundDrawablesRelativeWithIntrinsicBounds(
paymentOption.drawableResourceId,
0,
0,
0
)
} else {
paymentMethodButton.text = "Select"
paymentMethodButton.setCompoundDrawablesRelativeWithIntrinsicBounds(
null,
null,
null,
null
)
}
}
```
1. Por fim, chame [confirm](https://stripe.dev/stripe-android/paymentsheet/com.stripe.android.paymentsheet/-payment-sheet/-flow-controller/index.html#-479056656%2FFunctions%2F2002900378) para finalizar o pagamento. Quando o cliente termina, a descrição da compra é descartada e chama o [paymentResultCallback](https://stripe.dev/stripe-android/paymentsheet/com.stripe.android.paymentsheet/-payment-sheet-result-callback/index.html#237248767%2FFunctions%2F2002900378) passado anteriormente em `create`.
#### Android (Kotlin)
```kotlin
// ...
flowController.confirmPayment()
// ...
private fun onPaymentSheetResult(
paymentSheetResult: PaymentSheetResult
) {
when (paymentSheetResult) {
is PaymentSheetResult.Canceled -> {
// Payment canceled
}
is PaymentSheetResult.Failed -> {
// Payment Failed. See logcat for details or inspect paymentSheetResult.error
}
is PaymentSheetResult.Completed -> {
// Payment Complete
}
}
}
```
Configurar `allowsDelayedPaymentMethods` como verdadeiro permite formas de pagamento de [notificação assíncrona](https://docs.stripe.com/payments/payment-methods.md#payment-notification) como contas bancárias dos EUA. Para essas formas de pagamento, o status final do pagamento não é conhecido quando o `PaymentSheet` é concluído, sendo efetivado ou não posteriormente. Se você aceitar esses tipos de formas de pagamento, informe o cliente que seu pedido está confirmado e somente processe o pedido (por exemplo, fazendo o envio do produto) quando o pagamento for bem-sucedido.
## Optional: Habilitar formas de pagamento adicionais
Navegue para [Gerenciar formas de pagamento para suas contas conectadas](https://dashboard.stripe.com/settings/payment_methods/connected_accounts) no Dashboard para configurar quais formas de pagamento suas contas conectadas aceitam. As alterações nas configurações padrão se aplicam a todas as contas conectadas novas e existentes.
Consulte os seguintes recursos para obter informações sobre formas de pagamento:
- [Um guia de formas de pagamento](https://stripe.com/payments/payment-methods-guide#choosing-the-right-payment-methods-for-your-business) para ajudar você a escolher as formas de pagamento corretas para sua plataforma.
- [Funções da conta](https://docs.stripe.com/connect/account-capabilities.md) para assegurar que as formas de pagamento escolhidas funcionem para suas contas conectadas.
- Tabelas de [suporte a formas de pagamento e produtos](https://docs.stripe.com/payments/payment-methods/payment-method-support.md#product-support) para assegurar que suas formas de pagamento escolhidas funcionem para seus produtos da Stripe e fluxos de pagamento.
Para cada forma de pagamento, você pode selecionar uma das seguintes opções no menu suspenso:
| |
| |
| **Ativadas por padrão** | Suas contas conectadas aceitam esta forma de pagamento durante o checkout. Algumas formas de pagamento podem ser desativadas ou bloqueadas. Isso ocorre porque suas contas conectadas com *acesso ao Stripe Dashboard* (Platforms can provide connected accounts with access to the full Stripe Dashboard or the Express Dashboard. Otherwise, platforms build an interface for connected accounts using embedded components or the Stripe API) precisam ativá-las em sua página de configurações. |
| **Desativadas por padrão** | Suas contas conectadas não aceitam esta forma de pagamento durante o checkout. Se você permitir que contas conectadas com *acessem o Stripe Dashboard* (Platforms can provide connected accounts with access to the full Stripe Dashboard or the Express Dashboard. Otherwise, platforms build an interface for connected accounts using embedded components or the Stripe API) para gerenciar suas próprias formas de pagamento, elas podem ativar esse recurso. |
| **Bloqueadas** | Suas contas conectadas não aceitam esta forma de pagamento durante o checkout. Se você permitir que contas conectadas com *acessem o Stripe Dashboard* (Platforms can provide connected accounts with access to the full Stripe Dashboard or the Express Dashboard. Otherwise, platforms build an interface for connected accounts using embedded components or the Stripe API) para gerenciar suas próprias formas de pagamento, elas não têm a opção para ativar esse recurso. |
Opções de formas de pagamento
Se fizer uma alteração em uma forma de pagamento, você deve clicar em **Revisar alterações** na barra inferior da tela e em **Salvar e aplicar** para atualizar suas contas conectadas.
Salvar diálogo
### Permitir que contas conectadas gerenciem formas de pagamento
A Stripe recomenda permitir que as contas conectadas personalizem suas próprias formas de pagamento. Esta opção permite que cada conta conectada com *acesso ao Stripe Dashboard* (Platforms can provide connected accounts with access to the full Stripe Dashboard or the Express Dashboard. Otherwise, platforms build an interface for connected accounts using embedded components or the Stripe API) para ver e atualizar sua página de [formas de pagamento](https://dashboard.stripe.com/settings/payment_methods). Somente os proprietários das contas conectadas podem personalizar as formas de pagamento. O Stripe Dashboard exibe o conjunto de padrões de forma de pagamento que você aplicou a todas as contas conectadas novas e existentes. Suas contas conectadas podem sobrepor esses padrões, excluindo as formas de pagamento que você bloqueou.
Marque a caixa de seleção **Personalização da conta** para habilitar essa opção. Você deve clicar em **Revisar alterações** na barra inferior da tela e selecionar **Salvar e aplicar** para atualizar essa configuração.
Caixa de seleção de personalização da conta
### Funções das formas de pagamento
Para permitir que suas contas conectadas aceitem formas de pagamento adicionais, suas `Accounts` devem ter recursos de formas de pagamento ativas.
Se você selecionou a opção “On by default” (ativado por padrão) como método de pagamento em[Gerencie formas de pagamento para suas contas conectadas](https://dashboard.stripe.com/settings/payment_methods/connected_accounts), a Stripe solicita automaticamente a funcionalidade necessário para contas conectadas novas e existentes, caso atendam aos requisitos de verificação. Se a conta conectada não atender aos requisitos ou se você quiser ter controle direto, pode solicitação manualmente a funcionalidade no Dashboard ou na API.
A maioria das formas de pagamento possui os mesmos requisitos de verificação que a funcionalidade `card_payments`, com algumas restrições e exceções. A[tabela de formas de pagamento](https://docs.stripe.com/connect/account-capabilities.md#payment-methods) lista os métodos de pagamento que requerem verificação adicional.
#### Dashboard
[Encontre uma conta conectada](https://docs.stripe.com/connect/dashboard/managing-individual-accounts.md#finding-accounts) no Dashboard para editar suas capacidades e visualizar os requisitos de verificação pendentes.
#### API
Para uma conta conectada existente, você pode [listar](https://docs.stripe.com/api/capabilities/list.md) as funções existentes decidir se precisa solicitar funções adicionais.
```curl
curl https://api.stripe.com/v1/accounts/{{CONNECTEDACCOUNT_ID}}/capabilities \
-u "<>:"
```
Solicite funções adicionais [atualizando](https://docs.stripe.com/api/capabilities/update.md) as funções de cada conta conectada.
```curl
curl https://api.stripe.com/v1/accounts/{{CONNECTEDACCOUNT_ID}}/capabilities/us_bank_account_ach_payments \
-u "<>:" \
-d requested=true
```
Pode haver um atraso antes que a função solicitada se torne ativa. Se a função tiver algum requisito de ativação, ele será incluído nas matrizes de `requirements`.
## Coletar tarifas
Como plataforma, você pode cobrar de suas contas conectadas uma parte de cada transação na forma de tarifas da plataforma. Você pode definir a tarifa da plataforma das seguintes maneiras:
- Use a [ferramenta de preços da plataforma](https://docs.stripe.com/connect/platform-pricing-tools.md) para definir e testar regras de preços. No momento, esse recurso no-code no Stripe Dashboard só está disponível para plataformas responsáveis pelo pagamento das tarifas da Stripe.
- Especifique tarifas de aplicação diretamente em um [PaymentIntent](https://docs.stripe.com/api/payment_intents/object.md). As tarifas definidas com esse método substituem a lógica de precificação especificada na Platform Pricing Tool.
Sua plataforma pode cobrar uma tarifa da plataforma com as seguintes limitações:
- O valor de `application_fee_amount` deve ser positivo e inferior ao o valor da cobrança. A tarifa da plataforma recolhida é limitada ao valor capturado da cobrança.
- Não há tarifas adicionais da Stripe sobre a própria tarifa da plataforma.
- Em conformidade com os requisitos regulatórios e de conformidade do Brasil, plataformas sediadas fora do Brasil com contas conectadas brasileiras não podem recolher tarifas da plataforma por meio da Stripe.
- A moeda de `application_fee_amount` depende de alguns fatores de [várias moedas](https://docs.stripe.com/connect/currencies.md).
A [BalanceTransaction](https://docs.stripe.com/api.md#balance_transaction_retrieve) da cobrança resultante inclui um detalhamento das tarifas, tanto da Stripe quanto das tarifas da plataforma. Para proporcionar uma melhor experiência de relatórios, a cobrança de uma tarifa gera um objeto [ApplicationFee](https://docs.stripe.com/api/application_fees/object.md). Use a propriedade `amount`t no objeto `ApplicationFee` para fins de relatório.
Você pode visualizar as tarifas da plataforma na seção [tarifas cobradas](https://dashboard.stripe.com/connect/application_fees) do Dashboard.
> Por padrão, as tarifas da plataforma para cobranças diretas são criadas de forma assíncrona. Se você expandir o objeto `application_fee` em uma solicitação de criação de cobrança, a tarifa da plataforma será criada de forma síncrona como parte dessa solicitação. Somente expanda o objeto `application_fee` se for necessário, pois isso aumenta a latência da solicitação.
>
> Para receber notificações de objetos `ApplicationFee` criados de forma assíncrona, escute o evento de Webhook [application_fee.created](https://docs.stripe.com/api/events/types.md#event_types-application_fee.created).
Essa integração combina todas as etapas exigidas para pagar, incluindo coletar dados de pagamento e confirmar o pagamento, em uma única folha que é exibida na parte superior do seu aplicativo.
## Configurar a Stripe [Lado do servidor] [Lado do cliente]
Primeiro, você precisa de uma conta Stripe. [Cadastre-se agora](https://dashboard.stripe.com/register).
### Lado do servidor
Esta integração exige que os endpoints do seu servidor se comuniquem com a API da Stripe. Use as bibliotecas oficiais para acessar a API da Stripe pelo seu servidor:
#### 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'
```
### Lado do cliente
O [SDK do React Native](https://github.com/stripe/stripe-react-native) é de código aberto e totalmente documentado. Internamente, utiliza as SDKs de [iOS nativo](https://github.com/stripe/stripe-ios) e [Android](https://github.com/stripe/stripe-android). Para instalar o SDK do React Native da Stripe, execute um dos seguintes comandos no diretório do seu projeto (dependendo de qual gerenciador de pacotes você usa):
#### yarn
```bash
yarn add @stripe/stripe-react-native
```
#### npm
```bash
npm install @stripe/stripe-react-native
```
Em seguida, instale algumas outras dependências necessárias:
- Para iOS, vá para o diretório **ios** e execute `pod install` para garantir a instalação das dependências nativas necessárias.
- Para Android, não há mais dependências para instalar.
### Inicialização da Stripe
Para inicializar a Stripe no aplicativo React Native, insira sua tela de pagamento com o componente `StripeProvider` ou use o método de inicialização `initStripe`. Somente a [chave publicável](https://docs.stripe.com/keys.md#obtain-api-keys) da API em `publishableKey` é necessária. O exemplo a seguir mostra como inicializar a Stripe usando o componente `StripeProvider`.
```javascript
import { StripeProvider } from '@stripe/stripe-react-native';
function App() {
return (
// Your app code here
);
}
```
> Use suas [chaves de API de teste](https://docs.stripe.com/keys.md#obtain-api-keys) enquanto testa e desenvolve, e as chaves em [modo de produção](https://docs.stripe.com/keys.md#test-live-modes) quando publica seu aplicativo.
## Adicionar um endpoint [Lado do servidor]
> #### Nota
>
> Para exibir o PaymentSheet antes de criar um PaymentIntent, consulte [Colete os dados de pagamento antes de criar um Intent](https://docs.stripe.com/payments/accept-a-payment-deferred.md?type=payment).
Se a sua plataforma Connect utiliza [Contas configuradas pelo cliente](https://docs.stripe.com/api/v2/core/accounts/create.md#v2_create_accounts-configuration-customer), utilize o nosso [guia](https://docs.stripe.com/connect/use-accounts-as-customers.md) para substituir as referências a `Cliente` e eventos no seu código pelas referências equivalentes da API Accounts v2.
Esta integração usa três objetos da API da Stripe:
1. [PaymentIntent](https://docs.stripe.com/api/payment_intents.md): A Stripe usa isso para representar sua intenção de coletar o pagamento de um cliente, acompanhando suas tentativas de cobrança e alterações no estado do pagamento durante todo o processo.
1. (Opcional) [Customer](https://docs.stripe.com/api/customers.md): Para configurar uma forma de pagamento para pagamentos futuros, vincule-a a um *Customer* (Customer objects represent customers of your business. They let you reuse payment methods and give you the ability to track multiple payments). Crie um objeto Customer quando o cliente abrir uma conta na sua empresa. Se o cliente pagar como convidado, você pode criar o objeto Customer antes do pagamento e associá-lo à sua representação interna da conta do cliente, mais tarde.
1. (Opcional) [CustomerSession](https://docs.stripe.com/api/customer_sessions.md): Os dados do objeto Customer são confidenciais e não podem ser recuperados diretamente do aplicativo. Uma CustomerSession concede ao SDK acesso temporário com escopo definido ao cliente e fornece opções de configuração adicionais. Consulte uma lista completa de [opções de configuração](https://docs.stripe.com/api/customer_sessions/create.md#create_customer_session-components).
> Se você nunca salva cartões para um cliente e não permite que clientes retornando reutilizem cartões salvos, é possível omitir os objetos cliente e CustomerSession da sua integração.
Por motivos de segurança, o aplicativo não pode criar esses objetos. Para isso, adicione um endpoint ao servidor para:
1. Recuperar ou criar um Customer.
1. Cria uma [CustomerSession](https://docs.stripe.com/api/customer_sessions.md) para o cliente.
1. Cria um PaymentIntent com o [valor](https://docs.stripe.com/api/payment_intents/create.md#create_payment_intent-amount), a [moeda](https://docs.stripe.com/api/payment_intents/create.md#create_payment_intent-currency) e o [cliente](https://docs.stripe.com/api/payment_intents/create.md#create_payment_intent-customer).
1. Retorna o *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)) do Payment Intent, o `client_secret` da CustomerSession, o [id](https://docs.stripe.com/api/customers/object.md#customer_object-id) do Cliente e sua [chave publicável](https://dashboard.stripe.com/apikeys) para seu aplicativo.
As formas de pagamento mostradas aos clientes durante o processo de checkout também são incluídas no PaymentIntent. Você pode permitir que a Stripe obtenha as formas de pagamento das configurações do Dashboard ou listá-las manualmente. Independentemente da opção escolhida, saiba que a moeda passada no PaymentIntent filtra as formas de pagamento mostradas para o cliente. Por exemplo, se você passar EUR no `eur` e a OXXO estiver ativada no Dashboard, a OXXO não será exibida ao cliente porque a OXXO não aceita pagamentos em `eur`.
Se sua integração não exige uma opção baseada em código para oferecer formas de pagamento, a Stripe recomenda a opção automática. Isso ocorre porque a Stripe avalia a moeda, as restrições de forma de pagamento e outros parâmetros para determinar a lista de formas de pagamento aceitas. Priorizamos as formas de formas de pagamento que aumentam a conversão e que são mais relevantes para a moeda e a localização do cliente.
#### Gerenciar formas de pagamento no Dashboard
Você pode gerenciar formas de pagamento no [Dashboard](https://dashboard.stripe.com/settings/payment_methods). A Stripe processa a devolução de formas de pagamento qualificadas com base em fatores como valor, moeda e fluxo de pagamento da transação. O PaymentIntent é criado usando as formas de pagamento configuradas no Dashboard. Se não quiser usar o Dashboard ou se quiser especificar formas de pagamento manualmente, você pode listá-las usando o atributo `payment_method_types`.
#### curl
```bash
# Create a Customer (use an existing Customer ID if this is a returning customer)
curl https://api.stripe.com/v1/customers \
-u <>: \
-X "POST" \
-H "Stripe-Account: {{CONNECTED_ACCOUNT_ID}}"
# Create an CustomerSession for the Customer
curl https://api.stripe.com/v1/customer_sessions \
-u <>: \
-X "POST" \
-d "customer"="{{CUSTOMER_ID}}" \
-d "components[mobile_payment_element][enabled]"=true \
-d "components[mobile_payment_element][features][payment_method_save]"=enabled \
-d "components[mobile_payment_element][features][payment_method_redisplay]"=enabled \
-d "components[mobile_payment_element][features][payment_method_remove]"=enabled
# Create a PaymentIntent
curl https://api.stripe.com/v1/payment_intents \
-u <>: \
-H "Stripe-Account: {{CONNECTED_ACCOUNT_ID}}"
-X "POST" \
-d "customer"="{{CUSTOMER_ID}}" \
-d "amount"=1099 \
-d "currency"="eur" \
# In the latest version of the API, specifying the `automatic_payment_methods` parameter
# is optional because Stripe enables its functionality by default.
-d "automatic_payment_methods[enabled]"=true \
-d application_fee_amount="123" \
```
#### Listar manualmente as formas de pagamento
#### curl
```bash
# Create a Customer (use an existing Customer ID if this is a returning customer)
curl https://api.stripe.com/v1/customers \
-u <>: \
-X "POST" \
-H "Stripe-Account: {{CONNECTED_ACCOUNT_ID}}"
# Create an CustomerSession for the Customer
curl https://api.stripe.com/v1/customer_sessions \
-u <>: \
-X "POST" \
-d "customer"="{{CUSTOMER_ID}}" \
-d "components[mobile_payment_element][enabled]"=true \
-d "components[mobile_payment_element][features][payment_method_save]"=enabled \
-d "components[mobile_payment_element][features][payment_method_redisplay]"=enabled \
-d "components[mobile_payment_element][features][payment_method_remove]"=enabled
# Create a PaymentIntent
curl https://api.stripe.com/v1/payment_intents \
-u <>: \
-H "Stripe-Account: {{CONNECTED_ACCOUNT_ID}}"
-X "POST" \
-d "customer"="{{CUSTOMER_ID}}" \
-d "amount"=1099 \
-d "currency"="eur" \
-d "payment_method_types[]"="bancontact" \
-d "payment_method_types[]"="card" \
-d "payment_method_types[]"="ideal" \
-d "payment_method_types[]"="klarna" \
-d "payment_method_types[]"="sepa_debit" \
-d application_fee_amount="123" \
```
> A forma de pagamento precisa aceitar a moeda passada no PaymentIntent. Além disso, sua empresa precisa estar estabelecida em um dos países aceitos pela forma de pagamento. Consulte a página [Opções de integração de formas de pagamento](https://docs.stripe.com/payments/payment-methods/integration-options.md) para obter mais detalhes sobre o que é aceito.
## Integrar a descrição da compra [Lado do cliente]
Antes de exibir o Element Pagamento para dispositivos móveis, a página de checkout deve:
- Mostrar os produtos sendo comprados e o valor total
- Coletar todos os dados de entrega necessários
- Incluir um botão de checkout para apresentar a IU da Stripe
No checkout do aplicativo, faça uma solicitação de rede para o endpoint de backend criado por você na etapa anterior e chame o `initPaymentSheet` do hook `useStripe`.
```javascript
export default function CheckoutScreen() {
const { initPaymentSheet, presentPaymentSheet } = useStripe();
const [loading, setLoading] = useState(false);
const fetchPaymentSheetParams = async () => {
const response = await fetch(`${API_URL}/payment-sheet`, {
method: 'POST',
headers: {
'Content-Type': 'application/json',
},
});
const { paymentIntent, ephemeralKey, customer } = await response.json();
return {
paymentIntent,
ephemeralKey,
customer,
};
};
const initializePaymentSheet = async () => {
const {
paymentIntent,
ephemeralKey,
customer,
} = await fetchPaymentSheetParams();
const { error } = await initPaymentSheet({
merchantDisplayName: "Example, Inc.",
customerId: customer,
customerEphemeralKeySecret: ephemeralKey,
paymentIntentClientSecret: paymentIntent,
// Set `allowsDelayedPaymentMethods` to true if your business can handle payment
//methods that complete payment after a delay, like SEPA Debit and Sofort.
allowsDelayedPaymentMethods: true,
defaultBillingDetails: {
name: 'Jane Doe',
}
});
if (!error) {
setLoading(true);
}
};
const openPaymentSheet = async () => {
// see below
};
useEffect(() => {
initializePaymentSheet();
}, []);
return (
);
}
```
Quando o cliente tocar no botão **Checkout**, chame `presentPaymentSheet()` para abrir a descrição. Depois que o cliente finalizar o pagamento, a descrição será descartada e a promessa será resolvida com um `StripeError` opcional.
```javascript
export default function CheckoutScreen() {
// continued from above
const openPaymentSheet = async () => {
const { error } = await presentPaymentSheet();
if (error) {
Alert.alert(`Error code: ${error.code}`, error.message);
} else {
Alert.alert('Success', 'Your order is confirmed!');
}
};
return (
);
}
```
Se não houver erro, informe ao usuário que está tudo pronto (por exemplo, exibindo uma tela de confirmação de pedido).
Configurar `allowsDelayedPaymentMethods` como verdadeiro permite formas de pagamento de [notificação assíncrona](https://docs.stripe.com/payments/payment-methods.md#payment-notification) como contas bancárias dos EUA. Para essas formas de pagamento, o status final do pagamento não é conhecido quando o `PaymentSheet` é concluído, sendo efetivado ou não posteriormente. Se você aceitar esses tipos de formas de pagamento, informe o cliente que seu pedido está confirmado e somente processe o pedido (por exemplo, fazendo o envio do produto) quando o pagamento for bem-sucedido.
## Configurar um URL de retorno (somente iOS) [Lado do cliente]
O cliente pode sair do seu aplicativo para autenticar (por exemplo, no Safari ou no aplicativo bancário). Para permitir que eles voltem ao seu aplicativo após a autenticação, [configure um esquema de URL personalizado](https://developer.apple.com/documentation/xcode/defining-a-custom-url-scheme-for-your-app) e configure seu aplicativo delegado para encaminhar o URL ao SDK. A Stripe não aceita [links universais](https://developer.apple.com/documentation/xcode/allowing-apps-and-websites-to-link-to-your-content).
#### SceneDelegate
#### Swift
```swift
// This method handles opening custom URL schemes (for example, "your-app://stripe-redirect")
func scene(_ scene: UIScene, openURLContexts URLContexts: Set) {
guard let url = URLContexts.first?.url else {
return
}
let stripeHandled = StripeAPI.handleURLCallback(with: url)
if (!stripeHandled) {
// This was not a Stripe url – handle the URL normally as you would
}
}
```
#### AppDelegate
#### Swift
```swift
// This method handles opening custom URL schemes (for example, "your-app://stripe-redirect")
func application(_ app: UIApplication, open url: URL, options: [UIApplication.OpenURLOptionsKey: Any] = [:]) -> Bool {
let stripeHandled = StripeAPI.handleURLCallback(with: url)
if (stripeHandled) {
return true
} else {
// This was not a Stripe url – handle the URL normally as you would
}
return false
}
```
#### SwiftUI
#### Swift
```swift
@main
struct MyApp: App {
var body: some Scene {
WindowGroup {
Text("Hello, world!").onOpenURL { incomingURL in
let stripeHandled = StripeAPI.handleURLCallback(with: incomingURL)
if (!stripeHandled) {
// This was not a Stripe url – handle the URL normally as you would
}
}
}
}
}
```
Além disso, defina o [returnURL](https://stripe.dev/stripe-ios/stripe-paymentsheet/Classes/PaymentSheet/Configuration.html#/s:6Stripe12PaymentSheetC13ConfigurationV9returnURLSSSgvp) no seu objeto [PaymentSheet.Configuration](https://stripe.dev/stripe-ios/stripe-paymentsheet/Classes/PaymentSheet/Configuration.html) para o URL do seu aplicativo.
```swift
var configuration = PaymentSheet.Configuration()
configuration.returnURL = "your-app://stripe-redirect"
```
## Gerenciar 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 a [ferramenta Dashboard webhook](https://dashboard.stripe.com/webhooks) ou siga o [guia de webhooks](https://docs.stripe.com/webhooks/quickstart.md) para receber esses eventos e executar ações, como enviar um e-mail de confirmação do pedido ao cliente, registrar a venda em um banco de dados ou iniciar um fluxo de trabalho de envio.
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 sua integração para escutar eventos assíncronos é o que permite a você aceitar [diferentes tipos de formas de pagamento](https://stripe.com/payments/payment-methods-guide) com uma única integração.
Além de gerenciar o evento `payment_intent.succeeded`, recomendamos gerenciar esses outros eventos ao coletar pagamentos com o Element Pagamento:
| Evento | Descrição | Ação |
| ------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [payment_intent.succeeded](https://docs.stripe.com/api/events/types.md?lang=php#event_types-payment_intent.succeeded) | Enviado quando um cliente conclui um pagamento com êxito. | Envie ao cliente uma confirmação de pedido e *processe* (Fulfillment is the process of providing the goods or services purchased by a customer, typically after payment is collected) o pedido. |
| [payment_intent.processing](https://docs.stripe.com/api/events/types.md?lang=php#event_types-payment_intent.processing) | Enviado quando um cliente inicia um pagamento, mas o pagamento ainda precisa ser concluído. Esse evento costuma ser enviado quando um cliente inicia um débito bancário. Ele é seguido por um evento `payment_intent.succeeded` ou `payment_intent.payment_failed` no futuro. | Envie ao cliente uma confirmação do pedido que indica que o pagamento está pendente. Para produtos digitais, pode ser necessário executar o pedido antes de aguardar a conclusão do pagamento. |
| [payment_intent.payment_failed](https://docs.stripe.com/api/events/types.md?lang=php#event_types-payment_intent.payment_failed) | Enviado quando um cliente tenta fazer um pagamento, mas o pagamento falha. | Se um pagamento passa de `processing` para `payment_failed`, ofereça ao cliente outra tentativa para pagar. |
## Testar a integração
#### Cartões
| Número do cartão | Cenário | Como testar |
| ------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------- |
| 4242424242424242 | O pagamento com cartão é bem-sucedido e não precisa de autenticação. | Preencha o formulário do cartão de crédito usando o número do cartão de crédito com qualquer validade, CVC e código postal. |
| 4000002500003155 | O pagamento com cartão precisa de *autenticação* (Strong Customer Authentication (SCA) is a regulatory requirement in effect as of September 14, 2019, that impacts many European online payments. It requires customers to use two-factor authentication like 3D Secure to verify their purchase). | Preencha o formulário do cartão de crédito usando o número do cartão de crédito com qualquer validade, CVC e código postal. |
| 4000000000009995 | O cartão é recusado com um código de recusa como `insufficient_funds`. | Preencha o formulário do cartão de crédito usando o número do cartão de crédito com qualquer validade, CVC e código postal. |
| 6205500000000000004 | O cartão UnionPay tem um comprimento variável de 13 a 19 dígitos. | Preencha o formulário do cartão de crédito usando o número do cartão de crédito com qualquer validade, CVC e código postal. |
#### Débito bancário autenticado
| Forma de pagamento | Cenário | Como testar |
| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Bancontact, iDEAL | Seu cliente não faz a autenticação na página de redirecionamento de uma forma de pagamento baseada em redirecionamento e notificação imediata. | Escolha qualquer forma de pagamento baseada em redirecionamento, preencha os dados obrigatórios e confirme o pagamento. Em seguida, clique em **Falhar pagamento de teste** na página de redirecionamento. |
| Pay by Bank | O cliente paga com uma forma de pagamento baseada em redirecionamento e [notificação posterior](https://docs.stripe.com/payments/payment-methods.md#payment-notification). | Escolha a forma de pagamento, preencha os dados obrigatórios e confirme o pagamento. Em seguida, clique em **Concluir o pagamento de teste** na página de redirecionamento. |
| Pay by Bank | Seu cliente não faz a autenticação na página de redirecionamento de uma forma de pagamento baseada em redirecionamento e notificação posterior. | Escolha a forma de pagamento, preencha os dados obrigatórios e confirme o pagamento. Em seguida, clique em **Falhar o pagamento de teste** na página de redirecionamento. |
| BLIK | Os pagamentos BLIK falham de várias formas: falhas imediatas (por exemplo, o código está vencido ou inválido), erros atrasados (o banco recusa) ou limites de tempo (o cliente não respondeu a tempo). | Use padrões de e-mail para [simular as diferentes falhas.](https://docs.stripe.com/payments/blik/accept-a-payment.md#simulate-failures) |
#### Débitos bancários
| Forma de pagamento | Cenário | Como testar |
| ---------------------- | ------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Débito automático SEPA | O cliente paga com débito automático SEPA. | Preencha o formulário usando o número de conta `AT321904300235473204`. Inicialmente, o status do PaymentIntent muda para processando e, três minutos depois, para bem-sucedido. |
| Débito automático SEPA | O status da intenção de pagamento do cliente muda de `processing` para `requires_payment_method`. | Preencha o formulário usando o número de conta `AT861904300235473202`. |
Consulte [Testes](https://docs.stripe.com/testing.md) para obter mais informações sobre como testar sua integração.
## Habilitar leitura de cartões [Lado do cliente]
> Ativar a leitura de cartões é obrigatório para o processo de análise de aplicativos da Apple no iOS. No Android, a leitura de cartões não é obrigatória, mas recomendamos que seja habilitada.
### iOS
Para habilitar o suporte à leitura de cartões no iOS, defina `NSCameraUsageDescription` (**Privacy - Camera Usage Description**) no `Info.plist` do seu aplicativo e informe um motivo para o acesso à câmera (por exemplo, “Para ler cartões”).
### Android
To enable card scanning support, [request production access](https://developers.google.com/pay/api/android/guides/test-and-deploy/request-prod-access) to the Google Pay API from the [Google Pay and Wallet Console](https://pay.google.com/business/console?utm_source=devsite&utm_medium=devsite&utm_campaign=devsite).
- Se você ativou o Google Pay, o recurso de escaneamento de cartões está automaticamente disponível em nossa IU em dispositivos elegíveis. Para saber mais sobre dispositivos elegíveis, consulte as [restrições da API do Google Pay](https://developers.google.com/pay/payment-card-recognition/debit-credit-card-recognition)
- **Importante:** O recurso de escanear cartão só aparece em builds assinadas com a mesma chave de assinatura registrada no [Google Pay & Wallet Console](https://pay.google.com/business/console). Builds de teste ou debug usando chaves de assinatura diferentes (por exemplo, builds distribuídas pelo Firebase App Tester) não mostrarão a opção **Escanear cartão**. Para testar o escaneamento de cartão em versões pré-lançamento, você deve:
- Assinar suas builds de teste com a chave de assinatura de produção
- Adicionar sua impressão digital da chave de assinatura de teste ao Google Pay e Wallet Console
## Optional: Ativar Apple Pay
### Solicitar um ID de comerciante da Apple
Obtenha um ID de comerciante da Apple [solicitando um novo identificador](https://developer.apple.com/account/resources/identifiers/add/merchant) no site de desenvolvedores da Apple.
Preencha o formulário com descrição e identificador. A descrição é para seu controle e pode ser modificada no futuro. A Stripe recomenda que você use o nome do aplicativo como identificador (por exemplo, `merchant.com.{{YOUR_APP_NAME}}`).
### Criar um certificado do Apple Pay
Crie um certificado para criptografia de dados de pagamento pelo aplicativo.
Vá até [Configurações de certificado do iOS](https://dashboard.stripe.com/settings/ios_certificates) no Dashboard, clique em **Adicionar novo aplicativo** e siga o guia.
Baixe um arquivo de solicitação de assinatura de certificado (CSR) para obter um certificado seguro da Apple que permite usar o Apple Pay.
Um arquivo CSR deve ser usado para emitir exatamente um certificado. Se você trocar seu ID de comerciante da Apple, acesse as [Configurações de certificado do iOS](https://dashboard.stripe.com/settings/ios_certificates) no Dashboard para obter um novo CSR e certificado.
### Integrar com Xcode
Adicione as funções do Apple Pay ao aplicativo. No Xcode, abra as configurações do projeto, clique na guia **Signing & Capabilities** e adicione o recurso **Apple Pay**. Talvez seja necessário fazer login na sua conta de desenvolvedor. Selecione o ID de comerciante criado anteriormente e o aplicativo já pode aceitar Apple Pay.
Habilitar o recurso Apple Pay no Xcode
### Adicionar Apple Pay
#### Pagamento avulso
Passe seu ID de comerciante quando criar `StripeProvider`:
```javascript
import { StripeProvider } from '@stripe/stripe-react-native';
function App() {
return (
{/* Your app code here */}
);
}
```
Quando você chamar `initPaymentSheet`, passe seus [ApplePayParams](https://stripe.dev/stripe-react-native/api-reference/modules/PaymentSheet.html#ApplePayParams):
```javascript
await initPaymentSheet({
// ...
applePay: {
merchantCountryCode: 'US',
},
});
```
#### Pagamentos recorrentes
Quando você chamar `initPaymentSheet`, passe um [ApplePayParams](https://stripe.dev/stripe-react-native/api-reference/modules/PaymentSheet.html#ApplePayParams) com `merchantCountryCode` definido como o código de país da sua empresa.
In accordance with [Apple’s guidelines](https://developer.apple.com/design/human-interface-guidelines/apple-pay#Supporting-subscriptions) for recurring payments, you must also set a `cardItems` that includes a [RecurringCartSummaryItem](https://stripe.dev/stripe-react-native/api-reference/modules/ApplePay.html#RecurringCartSummaryItem) with the amount you intend to charge (for example, “59.95 USD a month”).
Você também pode adotar [tokens de comerciante](https://developer.apple.com/apple-pay/merchant-tokens/) definindo a `request` com seu `type` definido como `PaymentRequestType.Recurring`
Para saber como usar pagamentos recorrentes com Apple Pay, consulte a [documentação do PassKit da Apple](https://developer.apple.com/documentation/passkit/pkpaymentrequest).
#### iOS (React Native)
```javascript
const initializePaymentSheet = async () => {
const recurringSummaryItem = {
label: 'My Subscription',
amount: '59.99',
paymentType: 'Recurring',
intervalCount: 1,
intervalUnit: 'month',
// Payment starts today
startDate: new Date().getTime() / 1000,
// Payment ends in one year
endDate: new Date().getTime() / 1000 + 60 * 60 * 24 * 365,
};
const {error} = await initPaymentSheet({
// ...
applePay: {
merchantCountryCode: 'US',
cartItems: [recurringSummaryItem],
request: {
type: PaymentRequestType.Recurring,
description: 'Recurring',
managementUrl: 'https://my-backend.example.com/customer-portal',
billing: recurringSummaryItem,
billingAgreement:
"You'll be billed $59.99 every month for the next 12 months. To cancel at any time, go to Account and click 'Cancel Membership.'",
},
},
});
};
```
### Rastreamento de pedidos
Para adicionar informações de [rastreamento de pedido](https://developer.apple.com/design/human-interface-guidelines/technologies/wallet/designing-order-tracking) no iOS 16 ou mais recente, configure uma função de retorno de chamada `setOrderTracking`. A Stripe chama sua implementação após a conclusão do pagamento, mas antes que o iOS ignore a descrição de compra do Apple Pay.
Na implementação da função de retorno de chamada `setOrderTracking`, obtenha os detalhes do pedido concluído no seu servidor e passe esses dados à função de `completion` informada.
Para saber mais sobre rastreamento de pedidos, consulte a [documentação de pedidos da carteira da Apple](https://developer.apple.com/documentation/walletorders).
#### iOS (React Native)
```javascript
await initPaymentSheet({
// ...
applePay: {
// ...
setOrderTracking: async complete => {
const apiEndpoint =
Platform.OS === 'ios'
? 'http://localhost:4242'
: 'http://10.0.2.2:4567';
const response = await fetch(
`${apiEndpoint}/retrieve-order?orderId=${orderId}`,
{
method: 'GET',
headers: {
'Content-Type': 'application/json',
},
},
);
if (response.status === 200) {
const orderDetails = await response.json();
// orderDetails should include orderIdentifier, orderTypeIdentifier,
// authenticationToken and webServiceUrl
complete(orderDetails);
}
},
},
});
```
## Optional: Ativar Google Pay
### Configure a integração
Para usar o Google Pay, habilite a API Google Pay adicionando o seguinte à `` tag do seu **AndroidManifest.xml**:
```xml
...
```
Veja mais detalhes na [Configuração da API Google Pay](https://developers.google.com/pay/api/android/guides/setup) do Google Pay para Android.
### Adicionar Google Pay
Quando você inicializar `PaymentSheet`, defina `merchantCountryCode` como o código de país da sua empresa e defina `googlePay` como true.
Você também pode usar o ambiente de teste passando o parâmetro `testEnv`. Você só pode testar o Google Pay em um dispositivo Android físico. Siga a [documentação do React Native](https://reactnative.dev/docs/running-on-device) para testar seu aplicativo em um dispositivo físico.
```javascript
const { error, paymentOption } = await initPaymentSheet({
// ...
googlePay: {
merchantCountryCode: 'US',
testEnv: true, // use test environment
},
});
```
## Optional: Personalizar a descrição
Toda personalização é configurada usando `initPaymentSheet`.
### Aparência
Customize colors, fonts, and so on to match the look and feel of your app by using the [appearance API](https://docs.stripe.com/elements/appearance-api/mobile.md?platform=react-native).
### Nome de exibição do comerciante
Especifique o nome da empresa exibido para o cliente definindo `merchantDisplayName`. Por padrão, este é o nome do seu aplicativo.
```javascript
await initPaymentSheet({
// ...
merchantDisplayName: 'Example Inc.',
});
```
### Modo escuro
Por padrão, o `PaymentSheet` se adapta automaticamente às configurações de aparência do sistema do usuário (modo claro e escuro). É possível alterar isso configurando a propriedade `style` como modo `alwaysLight` ou `alwaysDark` no iOS.
```javascript
await initPaymentSheet({
// ...
style: 'alwaysDark',
});
```
No Android, configure o modo claro ou escuro no seu aplicativo:
```
// force dark
AppCompatDelegate.setDefaultNightMode(AppCompatDelegate.MODE_NIGHT_YES)
// force light
AppCompatDelegate.setDefaultNightMode(AppCompatDelegate.MODE_NIGHT_NO)
```
### Dados de faturamento padrão
Para definir valores padrão para dados de cobrança coletados no PaymentSheet, configure a propriedade `defaultBillingDetails`. A `PaymentSheet` preenche previamente seus campos com os valores que você informou.
```javascript
await initPaymentSheet({
// ...
defaultBillingDetails: {
email: 'foo@bar.com',
address: {
country: 'US',
},
},
});
```
### Coletar dados de cobrança
Use `billingDetailsCollectionConfiguration` para especificar como você deseja coletar dados de cobrança no PaymentSheet.
Você pode coletar o nome, e-mail, número de telefone e endereço do cliente.
Se não pretende coletar os valores exigidos pela forma de pagamento, faça o seguinte:
1. Anexe os valores não coletados por `PaymentSheet` à propriedade `defaultBillingDetails`.
1. Defina `billingDetailsCollectionConfiguration.attachDefaultsToPaymentMethod` como `true`.
```javascript
await initPaymentSheet({
// ...
defaultBillingDetails: {
email: 'foo@bar.com',
},
billingDetailsCollectionConfiguration: {
name: PaymentSheet.CollectionMode.ALWAYS,
email: PaymentSheet.CollectionMode.NEVER,
address: PaymentSheet.AddressCollectionMode.FULL,
attachDefaultsToPaymentMethod: true
},
});
```
> Consulte seu jurídico sobre as leis que se aplicam à coleta de dados. Só colete números de telefone se precisar deles para a transação.
## Optional: Conclua o pagamento em sua IU
Você pode exibir a Payment Sheet apenas para coletar dados da forma de pagamento e depois chamar um método `confirm` para concluir o pagamento na IU do aplicativo. Isso é útil quando você tem um botão de compra personalizado ou precisa de mais etapas após a coleta dos dados do pagamento.
> Um exemplo de integração está [disponível no GitHub](https://github.com/stripe/stripe-react-native/blob/master/example/src/screens/PaymentsUICustomScreen.tsx).
1. Primeiro, chame `initPaymentSheet` e passe `customFlow: true`. `initPaymentSheet` é resolvido com uma opção de pagamento inicial que contém uma imagem e um rótulo representando a forma de pagamento do cliente. Atualize a IU com esses dados.
```javascript
const {
initPaymentSheet,
presentPaymentSheet,
confirmPaymentSheetPayment,
} = useStripe()
const { error, paymentOption } = await initPaymentSheet({
customerId: customer,
customerEphemeralKeySecret: ephemeralKey,
paymentIntentClientSecret: paymentIntent,
customFlow: true,
merchantDisplayName: 'Example Inc.',
});
// Update your UI with paymentOption
```
1. Use `presentPaymentSheet` para coletar detalhes de pagamento. Quando o cliente termina, a folha se desfaz por si mesma e resolve a promessa. Atualize sua IU com os detalhes da forma de pagamento selecionada.
```javascript
const { error, paymentOption } = await presentPaymentSheet();
```
1. Use `confirmPaymentSheetPayment` para confirmar o pagamento. Isso é resolvido com o resultado do pagamento.
```javascript
const { error } = await confirmPaymentSheetPayment();
if (error) {
Alert.alert(`Error code: ${error.code}`, error.message);
} else {
Alert.alert(
'Success',
'Your order is confirmed!'
);
}
```
Configurar `allowsDelayedPaymentMethods` como verdadeiro permite formas de pagamento de [notificação assíncrona](https://docs.stripe.com/payments/payment-methods.md#payment-notification) como contas bancárias dos EUA. Para essas formas de pagamento, o status final do pagamento não é conhecido quando o `PaymentSheet` é concluído, sendo efetivado ou não posteriormente. Se você aceitar esses tipos de formas de pagamento, informe o cliente que seu pedido está confirmado e somente processe o pedido (por exemplo, fazendo o envio do produto) quando o pagamento for bem-sucedido.
## Optional: Habilitar formas de pagamento adicionais
Navegue para [Gerenciar formas de pagamento para suas contas conectadas](https://dashboard.stripe.com/settings/payment_methods/connected_accounts) no Dashboard para configurar quais formas de pagamento suas contas conectadas aceitam. As alterações nas configurações padrão se aplicam a todas as contas conectadas novas e existentes.
Consulte os seguintes recursos para obter informações sobre formas de pagamento:
- [Um guia de formas de pagamento](https://stripe.com/payments/payment-methods-guide#choosing-the-right-payment-methods-for-your-business) para ajudar você a escolher as formas de pagamento corretas para sua plataforma.
- [Funções da conta](https://docs.stripe.com/connect/account-capabilities.md) para assegurar que as formas de pagamento escolhidas funcionem para suas contas conectadas.
- Tabelas de [suporte a formas de pagamento e produtos](https://docs.stripe.com/payments/payment-methods/payment-method-support.md#product-support) para assegurar que suas formas de pagamento escolhidas funcionem para seus produtos da Stripe e fluxos de pagamento.
Para cada forma de pagamento, você pode selecionar uma das seguintes opções no menu suspenso:
| |
| |
| **Ativadas por padrão** | Suas contas conectadas aceitam esta forma de pagamento durante o checkout. Algumas formas de pagamento podem ser desativadas ou bloqueadas. Isso ocorre porque suas contas conectadas com *acesso ao Stripe Dashboard* (Platforms can provide connected accounts with access to the full Stripe Dashboard or the Express Dashboard. Otherwise, platforms build an interface for connected accounts using embedded components or the Stripe API) precisam ativá-las em sua página de configurações. |
| **Desativadas por padrão** | Suas contas conectadas não aceitam esta forma de pagamento durante o checkout. Se você permitir que contas conectadas com *acessem o Stripe Dashboard* (Platforms can provide connected accounts with access to the full Stripe Dashboard or the Express Dashboard. Otherwise, platforms build an interface for connected accounts using embedded components or the Stripe API) para gerenciar suas próprias formas de pagamento, elas podem ativar esse recurso. |
| **Bloqueadas** | Suas contas conectadas não aceitam esta forma de pagamento durante o checkout. Se você permitir que contas conectadas com *acessem o Stripe Dashboard* (Platforms can provide connected accounts with access to the full Stripe Dashboard or the Express Dashboard. Otherwise, platforms build an interface for connected accounts using embedded components or the Stripe API) para gerenciar suas próprias formas de pagamento, elas não têm a opção para ativar esse recurso. |
Opções de formas de pagamento
Se fizer uma alteração em uma forma de pagamento, você deve clicar em **Revisar alterações** na barra inferior da tela e em **Salvar e aplicar** para atualizar suas contas conectadas.
Salvar diálogo
### Permitir que contas conectadas gerenciem formas de pagamento
A Stripe recomenda permitir que as contas conectadas personalizem suas próprias formas de pagamento. Esta opção permite que cada conta conectada com *acesso ao Stripe Dashboard* (Platforms can provide connected accounts with access to the full Stripe Dashboard or the Express Dashboard. Otherwise, platforms build an interface for connected accounts using embedded components or the Stripe API) para ver e atualizar sua página de [formas de pagamento](https://dashboard.stripe.com/settings/payment_methods). Somente os proprietários das contas conectadas podem personalizar as formas de pagamento. O Stripe Dashboard exibe o conjunto de padrões de forma de pagamento que você aplicou a todas as contas conectadas novas e existentes. Suas contas conectadas podem sobrepor esses padrões, excluindo as formas de pagamento que você bloqueou.
Marque a caixa de seleção **Personalização da conta** para habilitar essa opção. Você deve clicar em **Revisar alterações** na barra inferior da tela e selecionar **Salvar e aplicar** para atualizar essa configuração.
Caixa de seleção de personalização da conta
### Funções das formas de pagamento
Para permitir que suas contas conectadas aceitem formas de pagamento adicionais, suas `Accounts` devem ter recursos de formas de pagamento ativas.
Se você selecionou a opção “On by default” (ativado por padrão) como método de pagamento em[Gerencie formas de pagamento para suas contas conectadas](https://dashboard.stripe.com/settings/payment_methods/connected_accounts), a Stripe solicita automaticamente a funcionalidade necessário para contas conectadas novas e existentes, caso atendam aos requisitos de verificação. Se a conta conectada não atender aos requisitos ou se você quiser ter controle direto, pode solicitação manualmente a funcionalidade no Dashboard ou na API.
A maioria das formas de pagamento possui os mesmos requisitos de verificação que a funcionalidade `card_payments`, com algumas restrições e exceções. A[tabela de formas de pagamento](https://docs.stripe.com/connect/account-capabilities.md#payment-methods) lista os métodos de pagamento que requerem verificação adicional.
#### Dashboard
[Encontre uma conta conectada](https://docs.stripe.com/connect/dashboard/managing-individual-accounts.md#finding-accounts) no Dashboard para editar suas capacidades e visualizar os requisitos de verificação pendentes.
#### API
Para uma conta conectada existente, você pode [listar](https://docs.stripe.com/api/capabilities/list.md) as funções existentes decidir se precisa solicitar funções adicionais.
```curl
curl https://api.stripe.com/v1/accounts/{{CONNECTEDACCOUNT_ID}}/capabilities \
-u "<>:"
```
Solicite funções adicionais [atualizando](https://docs.stripe.com/api/capabilities/update.md) as funções de cada conta conectada.
```curl
curl https://api.stripe.com/v1/accounts/{{CONNECTEDACCOUNT_ID}}/capabilities/us_bank_account_ach_payments \
-u "<>:" \
-d requested=true
```
Pode haver um atraso antes que a função solicitada se torne ativa. Se a função tiver algum requisito de ativação, ele será incluído nas matrizes de `requirements`.
## Coletar tarifas
Como plataforma, você pode cobrar de suas contas conectadas uma parte de cada transação na forma de tarifas da plataforma. Você pode definir a tarifa da plataforma das seguintes maneiras:
- Use a [ferramenta de preços da plataforma](https://docs.stripe.com/connect/platform-pricing-tools.md) para definir e testar regras de preços. No momento, esse recurso no-code no Stripe Dashboard só está disponível para plataformas responsáveis pelo pagamento das tarifas da Stripe.
- Especifique tarifas de aplicação diretamente em um [PaymentIntent](https://docs.stripe.com/api/payment_intents/object.md). As tarifas definidas com esse método substituem a lógica de precificação especificada na Platform Pricing Tool.
Sua plataforma pode cobrar uma tarifa da plataforma com as seguintes limitações:
- O valor de `application_fee_amount` deve ser positivo e inferior ao o valor da cobrança. A tarifa da plataforma recolhida é limitada ao valor capturado da cobrança.
- Não há tarifas adicionais da Stripe sobre a própria tarifa da plataforma.
- Em conformidade com os requisitos regulatórios e de conformidade do Brasil, plataformas sediadas fora do Brasil com contas conectadas brasileiras não podem recolher tarifas da plataforma por meio da Stripe.
- A moeda de `application_fee_amount` depende de alguns fatores de [várias moedas](https://docs.stripe.com/connect/currencies.md).
A [BalanceTransaction](https://docs.stripe.com/api.md#balance_transaction_retrieve) da cobrança resultante inclui um detalhamento das tarifas, tanto da Stripe quanto das tarifas da plataforma. Para proporcionar uma melhor experiência de relatórios, a cobrança de uma tarifa gera um objeto [ApplicationFee](https://docs.stripe.com/api/application_fees/object.md). Use a propriedade `amount`t no objeto `ApplicationFee` para fins de relatório.
Você pode visualizar as tarifas da plataforma na seção [tarifas cobradas](https://dashboard.stripe.com/connect/application_fees) do Dashboard.
> Por padrão, as tarifas da plataforma para cobranças diretas são criadas de forma assíncrona. Se você expandir o objeto `application_fee` em uma solicitação de criação de cobrança, a tarifa da plataforma será criada de forma síncrona como parte dessa solicitação. Somente expanda o objeto `application_fee` se for necessário, pois isso aumenta a latência da solicitação.
>
> Para receber notificações de objetos `ApplicationFee` criados de forma assíncrona, escute o evento de Webhook [application_fee.created](https://docs.stripe.com/api/events/types.md#event_types-application_fee.created).
## Emitir reembolsos
Além de criar cobranças em contas conectadas, as plataformas também podem criar reembolsos de cobranças em contas conectadas. [Crie um reembolso](https://docs.stripe.com/api.md#create_refund) usando a chave secreta da sua plataforma, estando [autenticado](https://docs.stripe.com/connect/authentication.md#stripe-account-header) com as credenciais da conta conectada.
As tarifas de plataforma não são reembolsadas automaticamente quando um reembolso é emitido. Sua plataforma deve reembolsar explicitamente a tarifa da plataforma ou a conta conectada, a conta na qual a cobrança foi criada, perderá esse valor. Você pode reembolsar uma tarifa da plataforma passando um valor **true** para `refund_application_fee` na solicitação de reembolso:
```curl
curl https://api.stripe.com/v1/refunds \
-u "<>:" \
-H "Stripe-Account: {{CONNECTEDACCOUNT_ID}}" \
-d charge="{{CHARGE_ID}}" \
-d refund_application_fee=true
```
Por padrão, toda a cobrança é reembolsada, mas você pode criar um reembolso parcial definindo um `amount` como um número inteiro positivo. Se o reembolso for ao valor total da cobrança, toda a tarifa da plataforma será reembolsada. Caso contrário, um valor proporcional da tarifa da plataforma será reembolsado. Como opção, você pode informar um valor `refund_application_fee` de **falso** e [reembolsar a tarifa da plataforma](https://docs.stripe.com/api.md#create_fee_refund) separadamente.
## Componentes integrados do Connect
[Componentes integrados do Connect](https://docs.stripe.com/connect/get-started-connect-embedded-components.md) suportam direct charges. Ao usar o [componente integrado de pagamentos](https://docs.stripe.com/connect/supported-embedded-components/payments.md), você pode permitir que suas contas conectadas visualizem informações de pagamento, capturem cobranças e gerenciem contestações pelo seu site.
Note: The following is a preview/demo component that behaves differently than live mode usage with real connected accounts. The actual component has more functionality than what might appear in this demo component. For example, for connected accounts without Stripe dashboard access (custom accounts), no user authentication is required in production.
Os seguintes componentes exibem informações sobre Direct Charges:
- [Componente de pagamentos](https://docs.stripe.com/connect/supported-embedded-components/payments.md): Exibe todos os pagamentos e contestações de uma conta.
- [Detalhes dos pagamentos](https://docs.stripe.com/connect/supported-embedded-components/payment-details.md): Exibe informações de um pagamento específico.
- [Componente de lista de contestações](https://docs.stripe.com/connect/supported-embedded-components/disputes-list.md): Exibe todas as contestações de uma conta.
- [Disputas para um componente de pagamento](https://docs.stripe.com/connect/supported-embedded-components/disputes-for-a-payment.md): Exibe as contestações para um único pagamento especificado. Você pode usá-lo para incluir a função de gerenciamento de contestação em uma página com sua IU de pagamentos.
## See also
- [Trabalhar com várias moedas](https://docs.stripe.com/connect/currencies.md)
- [Descrições no extrato com o Connect](https://docs.stripe.com/connect/statement-descriptors.md)