# Crie cobranças de destino Crie cobranças na conta da sua plataforma, colete tarifas e transfira imediatamente os fundos restantes para suas contas conectadas. ## Comece aqui: instale skills de agente A Stripe recomenda usar skills oficiais para integrar com a API seguindo práticas recomendadas. Siga as instruções abaixo para saber como. **Dica: use curl em vez de ferramentas Fetch.** Skills são arquivos markdown detalhados de 10 KB a 20 KB. Ferramentas Fetch fazem um resumo deles. `curl -sL` garante o conteúdo completo. **Usando `npx skills`**: verifique se `npx` está instalado no sistema. Se `npx` estiver disponível, execute `npx skills add https://docs.stripe.com --list` para listar os skills disponíveis e, depois, execute `npx skills add https://docs.stripe.com --yes --skill <--skill other-skills>` para instalar skills individuais. **Se `npx skills` não estiver disponível**: é possível usar curl para buscar o índice de skills disponíveis, o que eles fazem e seus arquivos em `https://docs.stripe.com/.well-known/skills/index.json`. Para baixar um skill e os arquivos relacionados, use curl para baixá-los de `https://docs.stripe.com/.well-known/skills/`. Para este artigo, recomendamos usar estes skills: `stripe-best-practices` Crie *cobranças de destino* quando os clientes fizerem transações com sua plataforma para produtos ou serviços fornecidos por suas contas conectadas e você transferir fundos imediatamente para suas contas conectadas. Com este tipo de cobrança: - Você cria uma cobrança na conta da sua plataforma. - Você determina se alguns ou todos os fundos são transferidos para a conta conectada. - O custo das tarifas da Stripe e de reembolsos ou estornos é debitado da sua conta. Esse tipo de cobrança é mais ideal para marketplaces como o Airbnb, um marketplace de aluguel residencial, ou a Lyft, um aplicativo de transporte por aplicativo. Com [certas exceções](https://docs.stripe.com/connect/account-capabilities.md#transfers-cross-border), se sua plataforma e uma conta conectada não estiverem na mesma região, você deve especificar a conta conectada como o [comerciante da liquidação](https://docs.stripe.com/connect/destination-charges.md#settlement-merchant) usando o parâmetro `on_behalf_of` no [Payment Intent](https://docs.stripe.com/api/payment_intents/create.md#create_payment_intent-on_behalf_of) ou `payment_intent_data.on_behalf_of` na [Checkout Session](https://docs.stripe.com/api/checkout/sessions/create.md#create_checkout_session-payment_intent_data-on_behalf_of). Recomendamos usar cobranças de destino para contas conectadas que não 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, bem como formas de pagamento aceitáveis. 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
``` #### Destino 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 "<>:" \ -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 "payment_intent_data[transfer_data][destination]={{CONNECTEDACCOUNT_ID}}" \ -d mode=payment \ --data-urlencode "success_url=https://example.com/success?session_id={CHECKOUT_SESSION_ID}" ``` | Parâmetro | Descrição | | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | [payment_intent_data[transfer_data][destination]](https://docs.stripe.com/api/checkout/sessions/create.md#create_checkout_session-payment_intent_data-transfer_data-destination) | Indica que se trata de uma Destination Charges. Uma Destination Charges significa que a cobrança é processada na plataforma e, em seguida, os fundos são transferidos de forma imediata e automática para o saldo pendente da conta conectada. | | [line_items](https://docs.stripe.com/api/checkout/sessions/create.md#create_checkout_session-line_items) | Os itens que o cliente está comprando. Os itens são exibidos no formulário de pagamento integrado. | | [success_url](https://docs.stripe.com/api/checkout/sessions/create.md#create_checkout_session-success_url) | A URL para onde o cliente é redirecionado após concluir um pagamento. Use o valor de `{CHECKOUT_SESSION_ID}` para recuperar a Sessão de Checkout e verificar seu status, a fim de decidir o que exibir ao cliente. Também é possível acrescentar [parâmetros de consulta personalizados](https://docs.stripe.com/payments/checkout/custom-success-page.md), que permanecem ao longo do processo de redirecionamento. | | [payment_intent_data[application_fee_amount]](https://docs.stripe.com/api/checkout/sessions/create.md#create_checkout_session-payment_intent_data-application_fee_amount) | O valor que sua plataforma planeja deduzir da transação. O valor total cobrado é imediatamente transferido da plataforma para a conta conectada especificada por `transfer_data[destination]` após a cobrança ser capturada. O `application_fee_amount` é então transferido de volta para a plataforma, e a tarifa da Stripe é deduzida do valor da plataforma. | (See full diagram at https://docs.stripe.com/connect/destination-charges) Ao processar cobranças de destino, o Checkout usa as configurações de marca da conta da sua plataforma. Consulte [personalizar marca](https://docs.stripe.com/connect/destination-charges.md#branding) para obter mais informações. #### Em nome de Crie uma cobrança de destino com o parâmetro `on_behalf_of` definido para o ID da conta conectada. O parâmetro `on_behalf_of` determina o [comerciante de liquidação](https://docs.stripe.com/connect/destination-charges.md#settlement-merchant), que é usado como padrão na sua conta da plataforma. Isso afeta: - Quem fornece a descrição no extrato vista pelo cliente - Quem fornece o endereço e telefone vistos pelo cliente - A moeda de liquidação da cobrança - A [página de marca do Checkout](https://docs.stripe.com/connect/destination-charges.md#branding) vista pelo cliente 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 "<>:" \ -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 "payment_intent_data[on_behalf_of]={{CONNECTEDACCOUNT_ID}}" \ -d "payment_intent_data[transfer_data][destination]={{CONNECTEDACCOUNT_ID}}" \ -d mode=payment \ --data-urlencode "success_url=https://example.com/success?session_id={CHECKOUT_SESSION_ID}" ``` | Parâmetro | Descrição | | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | [payment_intent_data[on_behalf_of]](https://docs.stripe.com/api/checkout/sessions/create.md#create_checkout_session-payment_intent_data-on_behalf_of) | O comerciante da liquidação. O padrão será a plataforma se o parâmetro não estiver presente. | | [payment_intent_data[transfer_data][destination]](https://docs.stripe.com/api/checkout/sessions/create.md#create_checkout_session-payment_intent_data-transfer_data-destination) | Indica que se trata de uma Destination Charges. Uma Destination Charges significa que a cobrança é processada na plataforma e, em seguida, os fundos são transferidos de forma imediata e automática para o saldo pendente da conta conectada. | | [line_items](https://docs.stripe.com/api/checkout/sessions/create.md#create_checkout_session-line_items) | Os itens que o cliente está comprando. Os itens são exibidos na página de checkout hospedada pela Stripe. | | [success_url](https://docs.stripe.com/api/checkout/sessions/create.md#create_checkout_session-success_url) | A URL para onde o cliente é redirecionado após concluir um pagamento. Use o valor de `{CHECKOUT_SESSION_ID}` para recuperar a Sessão de Checkout e verificar seu status, a fim de decidir o que exibir ao cliente. Também é possível acrescentar [parâmetros de consulta personalizados](https://docs.stripe.com/payments/checkout/custom-success-page.md), que permanecem ao longo do processo de redirecionamento. | | [payment_intent_data[application_fee_amount]](https://docs.stripe.com/api/checkout/sessions/create.md#create_checkout_session-payment_intent_data-application_fee_amount) | O valor que sua plataforma planeja deduzir da transação. O valor total cobrado é imediatamente transferido da plataforma para a conta conectada especificada por `transfer_data[destination]` após a cobrança ser capturada. O `application_fee_amount` é então transferido de volta para a plataforma, e a tarifa da Stripe é deduzida do valor da plataforma. | (See full diagram at https://docs.stripe.com/connect/destination-charges) ## 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: Habilite mais formas de pagamento #### Destino Configure formas de pagamento para a sua conta na [página Formas de pagamento](https://dashboard.stripe.com/settings/payment_methods) no Stripe Dashboard. Pagamentos por cartão, Google Pay e Apple Pay estão habilitados por padrão, mas você pode ativar e desativar formas de pagamento conforme a necessidade. Suas contas conectadas não podem personalizar suas próprias formas de pagamento. Antes de exibir o formulário de pagamento a um cliente, 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. O formulário de pagamento prioriza as formas de pagamento que aumentam a conversão e são mais relevantes para a moeda e o local do cliente. As formas de pagamento de prioridade menor ficam ocultas em um menu de navegação. #### Em nome de 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 suspensas para formas de pagamento, cada uma mostrando uma opção disponível (bloqueadas, ativadas por padrão, desativadas por padrão)](https://b.stripecdn.com/docs-statics-srv/assets/dropdowns.ef651d721d5939d81521dd34dde4577f.png) 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. ![Diálogo exibido após clicar no botão Salvar, com uma lista das alterações feitas pelo usuário](https://b.stripecdn.com/docs-statics-srv/assets/dialog.a56ea7716f60db9778706790320d13be.png) 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. ![Captura de tela da caixa de seleção a ser marcada ao permitir que proprietários conectados personalizem formas de pagamento](https://b.stripecdn.com/docs-statics-srv/assets/checkbox.275bd35d2a025272f03af029a144e577.png) 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`. ## Tarifas cobradas Quando um pagamento é processado, em vez de transferir o valor total da transação para uma conta conectada, sua plataforma pode decidir cobrar uma parte do valor da transação na forma de tarifas. Você pode definir os preços das tarifas de duas maneiras diferentes: - Use a [ferramenta de preços da plataforma](https://docs.stripe.com/connect/platform-pricing-tools.md) para definir e testar as regras de preços das tarifas da plataforma. No momento, esse recurso no-code no Stripe Dashboard só está disponível para plataformas responsáveis pelo pagamento das tarifas da Stripe. - Defina internamente as regras de preços, especificando as tarifas diretamente em um [PaymentIntent](https://docs.stripe.com/api/payment_intents/object.md) usando o parâmetro [application_fee_amount](https://docs.stripe.com/api/payment_intents/object.md#payment_intent_object-application_fee_amount) ou [transfer_data[amount]](https://docs.stripe.com/api/payment_intents/object.md#payment_intent_object-transfer_data-amount). As tarifas definidas com esse método substituem a lógica de preços especificada na ferramenta de preços da plataforma. #### application_fee_amount Ao criar cobranças com `application_fee_amount`, o valor total da cobrança é imediatamente transferido da plataforma para a conta `transfer_data[destination]` depois que a cobrança é capturada. O valor `application_fee_amount` (limitado ao valor total da cobrança) é transferido de volta à plataforma em seguida. ```curl curl https://api.stripe.com/v1/checkout/sessions \ -u "<>:" \ -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 "payment_intent_data[transfer_data][destination]={{CONNECTEDACCOUNT_ID}}" \ -d mode=payment \ --data-urlencode "success_url=https://example.com/success" ``` Depois que a tarifa da plataforma é recolhida, é criado um objeto de [tarifa da plataforma](https://docs.stripe.com/api/application_fees/object.md). Você pode visualizar uma lista de tarifas da plataforma no [Dashboard](https://dashboard.stripe.com/connect/application_fees), com as [tarifas da plataforma](https://docs.stripe.com/api/application_fees/list.md), ou no [Sigma](https://docs.stripe.com/stripe-data/how-sigma-works.md). Você também pode usar a propriedade `amount` no objeto de tarifa da plataforma para relatórios de tarifas discriminadas. Quando usar um `application_fee_amount`, lembre-se: - O `application_fee_amount` é limitado ao valor total da transação. - O `application_fee_amount` é sempre computado na mesma moeda da transação. - A tarifa da plataforma é *liquidada* (When funds are available in your Stripe balance) na mesma moeda de liquidação da conta conectada. Para cobranças de destino internacionais, isso pode [diferir da moeda de liquidação da sua plataforma](https://docs.stripe.com/connect/currencies/fx-quotes-api.md#application-fees-for-destination-charges-and-converting-balances). - Sua plataforma paga a tarifa da Stripe após a transferência do `application_fee_amount` para sua conta. - Nenhuma tarifa da Stripe adicional é aplicada ao valor. - Sua plataforma pode usar relatórios integrados de tarifas da plataforma para reconciliar as [tarifas cobradas](https://dashboard.stripe.com/connect/application_fees). - Em dashboards ou componentes hospedados na Stripe como o [componente de detalhes do pagamento](https://docs.stripe.com/connect/supported-embedded-components/payment-details.md), sua conta conectada pode visualizar o valor total e o valor da tarifa da plataforma. ### Fluxo de fundos com Destination Charges Com o código acima, o valor total da cobrança (US$ 10,00) é adicionado ao saldo pendente da conta conectada. O valor `application_fee_amount` (US$ 1,23) é subtraído do valor da cobrança e transferido para sua plataforma. As tarifas da Stripe (US$ 0,59) são subtraídas do saldo da conta da plataforma. O valor da tarifa da plataforma, deduzido das tarifas da Stripe (US$ 1,23 - US$ 0,59 = US$ 0,64), permanece no saldo da conta da plataforma. ![Fluxo de fundos para Destination Charges](https://b.stripecdn.com/docs-statics-srv/assets/destination_charge_app_fee.c9ef81298155b38f986df02d0efa9167.png) O `application_fee_amount` é disponibilizado no cronograma de transferências normal da conta da plataforma, assim como os fundos das cobranças normais da Stripe. #### transfer_data[amount] O `transfer_data[amount]` é um inteiro positivo que indica o valor da cobrança a ser transferido para `transfer_data[destination]`. Você subtrai as tarifas da plataforma do valor da cobrança e passa o resultado desse cálculo como `transfer_data[amount]`. ```curl curl https://api.stripe.com/v1/checkout/sessions \ -u "<>:" \ -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[transfer_data][amount]=877" \ -d "payment_intent_data[transfer_data][destination]={{CONNECTEDACCOUNT_ID}}" \ -d mode=payment \ --data-urlencode "success_url=https://example.com/success" ``` Ao usar `transfer_data[amount]`, lembre-se: - O valor é limitado ao valor total da transação. - O valor é sempre computado na mesma moeda da transação. - O valor é *liquidado* (When funds are available in your Stripe balance) na [mesma moeda de liquidação da sua plataforma](https://docs.stripe.com/connect/currencies/fx-quotes-api.md#application-fees-for-destination-charges-and-converting-balances). - Nos dashboards hospedados em Stripe ou em componentes como o Stripe Dashboard ou Express Dashboard, sua conta conectada não consegue visualizar o valor total da cobrança. Ela só vê o valor transferido. - Sua plataforma paga separadamente as tarifas da Stripe sobre a cobrança. - Nenhuma tarifa da Stripe adicional é aplicada ao valor. - Para [calcular tarifas](https://docs.stripe.com/stripe-data/query-all-fees-data.md#fees-paid-by-connected-accounts) após a criação de um pagamento, como para fins de relatório, [acesse o PaymentIntent](https://docs.stripe.com/api/payment_intents/retrieve.md) e subtraia o `transfer_data[amount]` do `amount` no PaymentIntent. Considere usar o [valor da tarifa da plataforma](https://docs.stripe.com/connect/destination-charges.md#application-fee) para simplificar a declaração, criando tarifas de plataforma explícitas vinculadas à cobrança. ### Fluxo de fundos Com o código acima, o `amount` da cobrança (US$ 10,00) é adicionado ao saldo da conta da plataforma. O `transfer_data[amount]` (US$ 8,77) é subtraído do saldo da conta da plataforma e adicionado ao saldo pendente da conta conectada. O `amount` da cobrança (US$ 10,00) menos o `transfer_data[amount]` (US$ 8,77) menos as tarifas da Stripe (sobre o `amount` da cobrança), totalizando US$ 0,64, permanece no saldo pendente da conta da plataforma. ![](https://b.stripecdn.com/docs-statics-srv/assets/destination_charge_amount.46cd59f6496607d68020b546aa1af85f.png) O `transfer_data[amount]` é disponibilizado de acordo com o cronograma de transferências normal da conta conectada, da mesma forma que os fundos das cobranças normais da Stripe. As plataformas podem acompanhar o valor retido das cobranças de `transfer_data[amount]` na coluna “Tarifa da plataforma de destino” na exportação do histórico do saldo. ## 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 do pedido. 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. #### Destino ```curl curl https://api.stripe.com/v1/checkout/sessions \ -u "<>:" \ -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 "payment_intent_data[transfer_data][destination]={{CONNECTEDACCOUNT_ID}}" \ -d mode=payment \ -d ui_mode=embedded_page \ --data-urlencode "return_url=https://example.com/checkout/return?session_id={CHECKOUT_SESSION_ID}" ``` | Parâmetro | Descrição | | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | [payment_intent_data[transfer_data][destination]](https://docs.stripe.com/api/checkout/sessions/create.md#create_checkout_session-payment_intent_data-transfer_data-destination) | Indica que se trata de uma Destination Charges. Uma Destination Charges significa que a cobrança é processada na plataforma e, em seguida, os fundos são transferidos de forma imediata e automática para o saldo pendente da conta conectada. | | [line_items](https://docs.stripe.com/api/checkout/sessions/create.md#create_checkout_session-line_items) | Os itens que o cliente está comprando. Os itens são exibidos na página de checkout hospedada pela Stripe. | | [return_url](https://docs.stripe.com/api/checkout/sessions/create.md#create_checkout_session-return_url) | A URL para a qual o cliente é redirecionado depois de concluir um pagamento. Use o valor de `{CHECKOUT_SESSION_ID}` para recuperar a Sessão de Checkout e verificar seu status, a fim de decidir o que exibir ao cliente. Certifique-se de que a URL de retorno corresponda a uma página do seu site que informe o status do pagamento. Também é possível acrescentar [parâmetros de consulta personalizados](https://docs.stripe.com/payments/checkout/custom-success-page.md?payment-ui=embedded-form), que permanecem ao longo do processo de redirecionamento. | | [payment_intent_data[application_fee_amount]](https://docs.stripe.com/api/checkout/sessions/create.md#create_checkout_session-payment_intent_data-application_fee_amount) | O valor que sua plataforma planeja deduzir da transação. O valor total cobrado é imediatamente transferido da plataforma para a conta conectada especificada por `transfer_data[destination]` após a cobrança ser capturada. O `application_fee_amount` é então transferido de volta para a plataforma, e a tarifa da Stripe é deduzida do valor da plataforma. | (See full diagram at https://docs.stripe.com/connect/destination-charges) Ao realizar cobranças de destino, o Checkout usa as configurações de marca da conta da sua plataforma. Consulte [personalizar marca](https://docs.stripe.com/connect/destination-charges.md#branding) para obter mais informações. #### Em nome de Crie uma cobrança de destino com o parâmetro `on_behalf_of` definido como o ID da conta conectada (por padrão, é a plataforma). O parâmetro `on_behalf_of` determina o [comerciante de liquidação](https://docs.stripe.com/connect/destination-charges.md#settlement-merchant), que afeta: - Quem fornece a descrição no extrato vista pelo cliente - Quem fornece o endereço e telefone vistos pelo cliente - A moeda de liquidação da cobrança - A [página de marca do Checkout](https://docs.stripe.com/connect/destination-charges.md#branding) vista pelo cliente ```curl curl https://api.stripe.com/v1/checkout/sessions \ -u "<>:" \ -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 "payment_intent_data[on_behalf_of]={{CONNECTEDACCOUNT_ID}}" \ -d "payment_intent_data[transfer_data][destination]={{CONNECTEDACCOUNT_ID}}" \ -d mode=payment \ -d ui_mode=embedded_page \ --data-urlencode "return_url=https://example.com/return?session_id={CHECKOUT_SESSION_ID}" ``` | Parâmetro | Descrição | | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | [payment_intent_data[on_behalf_of]](https://docs.stripe.com/api/checkout/sessions/create.md#create_checkout_session-payment_intent_data-on_behalf_of) | Esse parâmetro determina o comerciante da liquidação, que será, por padrão, a plataforma se o parâmetro não for passado. | | [payment_intent_data[transfer_data][destination]](https://docs.stripe.com/api/checkout/sessions/create.md#create_checkout_session-payment_intent_data-transfer_data-destination) | Indica que se trata de uma Destination Charges. Uma Destination Charges significa que a cobrança é processada na plataforma e, em seguida, os fundos são transferidos de forma imediata e automática para o saldo pendente da conta conectada. | | [line_items](https://docs.stripe.com/api/checkout/sessions/create.md#create_checkout_session-line_items) | Representa os itens que o cliente está comprando. Os itens são exibidos na página de checkout hospedada pela Stripe. | | [return_url](https://docs.stripe.com/api/checkout/sessions/create.md#create_checkout_session-return_url) | A URL para a qual o cliente é redirecionado depois de concluir um pagamento. Use o valor de `{CHECKOUT_SESSION_ID}` para recuperar a Sessão de Checkout e verificar seu status, a fim de decidir o que exibir ao cliente. Certifique-se de que a URL de retorno corresponda a uma página do seu site que informe o status do pagamento. Também é possível acrescentar [parâmetros de consulta personalizados](https://docs.stripe.com/payments/checkout/custom-success-page.md?payment-ui=embedded-form), que permanecem ao longo do processo de redirecionamento. | | [payment_intent_data[application_fee_amount]](https://docs.stripe.com/api/checkout/sessions/create.md#create_checkout_session-payment_intent_data-application_fee_amount) | O valor que sua plataforma planeja deduzir da transação. O valor total cobrado é imediatamente transferido da plataforma para a conta conectada especificada por `transfer_data[destination]` após a cobrança ser capturada. O `application_fee_amount` é então transferido de volta para a plataforma, e a tarifa da Stripe é deduzida do valor da plataforma. | (See full diagram at https://docs.stripe.com/connect/destination-charges) ## Montar Checkout [Lado do cliente] #### HTML + JS O Checkout está disponível no [Stripe.js](https://docs.stripe.com/js.md). Inclua o script Stripe.js na página, adicionando-o ao cabeçalho do arquivo HTML. Crie um nó DOM vazio (contêiner) para usar na montagem. ```html
``` Inicialize o Stripe.js com sua chave de API publicável. Passe o `client_secret` da etapa anterior para `options` quando criar a instância do Checkout: ```javascript // Initialize Stripe.js const stripe = Stripe('<>'); 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.createEmbeddedCheckoutPage({ fetchClientSecret, }); // Mount Checkout checkout.mount('#checkout'); } ``` #### Reagir Instale as bibliotecas Connect.js e React Connect.js a partir do [registro público do npm](https://www.npmjs.com/package/@stripe/react-connect-js). ```bash npm install --save @stripe/connect-js @stripe/react-connect-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('<>'); 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: Habilite mais formas de pagamento #### Destino Configure formas de pagamento para a sua conta na [página Formas de pagamento](https://dashboard.stripe.com/settings/payment_methods) no Stripe Dashboard. Pagamentos por cartão, Google Pay e Apple Pay estão habilitados por padrão, mas você pode ativar e desativar formas de pagamento conforme a necessidade. Suas contas conectadas não podem personalizar suas próprias formas de pagamento. Antes de exibir o formulário de pagamento a um cliente, 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. O formulário de pagamento prioriza as formas de pagamento que aumentam a conversão e são mais relevantes para a moeda e o local do cliente. As formas de pagamento de prioridade menor ficam ocultas em um menu de navegação. #### Em nome de 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 suspensas para formas de pagamento, cada uma mostrando uma opção disponível (bloqueadas, ativadas por padrão, desativadas por padrão)](https://b.stripecdn.com/docs-statics-srv/assets/dropdowns.ef651d721d5939d81521dd34dde4577f.png) 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. ![Diálogo exibido após clicar no botão Salvar, com uma lista das alterações feitas pelo usuário](https://b.stripecdn.com/docs-statics-srv/assets/dialog.a56ea7716f60db9778706790320d13be.png) 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. ![Captura de tela da caixa de seleção a ser marcada ao permitir que proprietários conectados personalizem formas de pagamento](https://b.stripecdn.com/docs-statics-srv/assets/checkbox.275bd35d2a025272f03af029a144e577.png) 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`. ## Tarifas cobradas Quando um pagamento é processado, em vez de transferir o valor total da transação para uma conta conectada, sua plataforma pode decidir cobrar uma parte do valor da transação na forma de tarifas. Você pode definir os preços das tarifas de duas maneiras diferentes: - Use a [ferramenta de preços da plataforma](https://docs.stripe.com/connect/platform-pricing-tools.md) para definir e testar as regras de preços das tarifas da plataforma. No momento, esse recurso no-code no Stripe Dashboard só está disponível para plataformas responsáveis pelo pagamento das tarifas da Stripe. - Defina internamente as regras de preços, especificando as tarifas diretamente em um [PaymentIntent](https://docs.stripe.com/api/payment_intents/object.md) usando o parâmetro [application_fee_amount](https://docs.stripe.com/api/payment_intents/object.md#payment_intent_object-application_fee_amount) ou [transfer_data[amount]](https://docs.stripe.com/api/payment_intents/object.md#payment_intent_object-transfer_data-amount). As tarifas definidas com esse método substituem a lógica de preços especificada na ferramenta de preços da plataforma. #### application_fee_amount Ao criar cobranças com `application_fee_amount`, o valor total da cobrança é imediatamente transferido da plataforma para a conta `transfer_data[destination]` depois que a cobrança é capturada. O valor `application_fee_amount` (limitado ao valor total da cobrança) é transferido de volta à plataforma em seguida. ```curl curl https://api.stripe.com/v1/checkout/sessions \ -u "<>:" \ -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 "payment_intent_data[transfer_data][destination]={{CONNECTEDACCOUNT_ID}}" \ -d mode=payment \ -d ui_mode=embedded_page \ --data-urlencode "success_url=https://example.com/success" ``` Depois que a tarifa da plataforma é recolhida, é criado um objeto de [tarifa da plataforma](https://docs.stripe.com/api/application_fees/object.md). Você pode visualizar uma lista de tarifas da plataforma no [Dashboard](https://dashboard.stripe.com/connect/application_fees), com as [tarifas da plataforma](https://docs.stripe.com/api/application_fees/list.md), ou no [Sigma](https://docs.stripe.com/stripe-data/how-sigma-works.md). Você também pode usar a propriedade `amount` no objeto de tarifa da plataforma para relatórios de tarifas discriminadas. Quando usar um `application_fee_amount`, lembre-se: - O `application_fee_amount` é limitado ao valor total da transação. - O `application_fee_amount` é sempre computado na mesma moeda da transação. - A tarifa da plataforma é *liquidada* (When funds are available in your Stripe balance) na mesma moeda de liquidação da conta conectada. Para cobranças de destino internacionais, isso pode [diferir da moeda de liquidação da sua plataforma](https://docs.stripe.com/connect/currencies/fx-quotes-api.md#application-fees-for-destination-charges-and-converting-balances). - Sua plataforma paga a tarifa da Stripe após a transferência do `application_fee_amount` para sua conta. - Nenhuma tarifa da Stripe adicional é aplicada ao valor. - Sua plataforma pode usar relatórios integrados de tarifas da plataforma para reconciliar as [tarifas cobradas](https://dashboard.stripe.com/connect/application_fees). - Em dashboards ou componentes hospedados na Stripe como o [componente de detalhes do pagamento](https://docs.stripe.com/connect/supported-embedded-components/payment-details.md), sua conta conectada pode visualizar o valor total e o valor da tarifa da plataforma. ### Fluxo de fundos com Destination Charges Com o código acima, o valor total da cobrança (US$ 10,00) é adicionado ao saldo pendente da conta conectada. O valor `application_fee_amount` (US$ 1,23) é subtraído do valor da cobrança e transferido para sua plataforma. As tarifas da Stripe (US$ 0,59) são subtraídas do saldo da conta da plataforma. O valor da tarifa da plataforma, deduzido das tarifas da Stripe (US$ 1,23 - US$ 0,59 = US$ 0,64), permanece no saldo da conta da plataforma. ![Fluxo de fundos para Destination Charges](https://b.stripecdn.com/docs-statics-srv/assets/destination_charge_app_fee.c9ef81298155b38f986df02d0efa9167.png) O `application_fee_amount` é disponibilizado no cronograma de transferências normal da conta da plataforma, assim como os fundos das cobranças normais da Stripe. #### transfer_data[amount] O `transfer_data[amount]` é um inteiro positivo que indica o valor da cobrança a ser transferido para `transfer_data[destination]`. Você subtrai as tarifas da plataforma do valor da cobrança e passa o resultado desse cálculo como `transfer_data[amount]`. ```curl curl https://api.stripe.com/v1/checkout/sessions \ -u "<>:" \ -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[transfer_data][amount]=877" \ -d "payment_intent_data[transfer_data][destination]={{CONNECTEDACCOUNT_ID}}" \ -d mode=payment \ -d ui_mode=embedded_page \ --data-urlencode "success_url=https://example.com/success" ``` Ao usar `transfer_data[amount]`, lembre-se: - O valor é limitado ao valor total da transação. - O valor é sempre computado na mesma moeda da transação. - O valor é *liquidado* (When funds are available in your Stripe balance) na [mesma moeda de liquidação da sua plataforma](https://docs.stripe.com/connect/currencies/fx-quotes-api.md#application-fees-for-destination-charges-and-converting-balances). - Nos dashboards hospedados em Stripe ou em componentes como o Stripe Dashboard ou Express Dashboard, sua conta conectada não consegue visualizar o valor total da cobrança. Ela só vê o valor transferido. - Sua plataforma paga separadamente as tarifas da Stripe sobre a cobrança. - Nenhuma tarifa da Stripe adicional é aplicada ao valor. - Para [calcular tarifas](https://docs.stripe.com/stripe-data/query-all-fees-data.md#fees-paid-by-connected-accounts) após a criação de um pagamento, como para fins de relatório, [acesse o PaymentIntent](https://docs.stripe.com/api/payment_intents/retrieve.md) e subtraia o `transfer_data[amount]` do `amount` no PaymentIntent. Considere usar o [valor da tarifa da plataforma](https://docs.stripe.com/connect/destination-charges.md#application-fee) para simplificar a declaração, criando tarifas de plataforma explícitas vinculadas à cobrança. ### Fluxo de fundos Com o código acima, o `amount` da cobrança (US$ 10,00) é adicionado ao saldo da conta da plataforma. O `transfer_data[amount]` (US$ 8,77) é subtraído do saldo da conta da plataforma e adicionado ao saldo pendente da conta conectada. O `amount` da cobrança (US$ 10,00) menos o `transfer_data[amount]` (US$ 8,77) menos as tarifas da Stripe (sobre o `amount` da cobrança), totalizando US$ 0,64, permanece no saldo pendente da conta da plataforma. ![](https://b.stripecdn.com/docs-statics-srv/assets/destination_charge_amount.46cd59f6496607d68020b546aa1af85f.png) O `transfer_data[amount]` é disponibilizado de acordo com o cronograma de transferências normal da conta conectada, da mesma forma que os fundos das cobranças normais da Stripe. As plataformas podem acompanhar o valor retido das cobranças de `transfer_data[amount]` na coluna “Tarifa da plataforma de destino” na exportação do histórico do saldo. ## 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 com 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/destination-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 habilitados. 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 "<>:" \ -d amount=1000 \ -d currency=usd \ -d "automatic_payment_methods[enabled]=true" \ -d application_fee_amount=123 \ -d "transfer_data[destination]={{CONNECTEDACCOUNT_ID}}" ``` #### Listar manualmente as formas de pagamento Crie um PaymentIntent no seu servidor com valor, moeda e uma lista de tipos de formas de pagamento. Sempre decida quanto deseja cobrar no lado do servidor, um ambiente seguro, e não no lado do cliente, para evitar que clientes mal-intencionados escolham os próprios preços. ```curl curl https://api.stripe.com/v1/payment_intents \ -u "<>:" \ -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 application_fee_amount=123 \ -d "transfer_data[destination]={{CONNECTEDACCOUNT_ID}}" ``` Escolha a moeda de acordo com as formas de pagamento que pretende aceitar. Algumas formas de pagamento aceitam várias moedas e países. Este exemplo usa Bancontact, cartões de crédito, EPS, iDEAL, Przelewy24 e débito automático SEPA. > 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 as [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 diversas formas de pagamento. O Payment Element contém um iframe que envia dados de pagamento com segurança à Stripe por uma conexão HTTPS. Evite colocar o Payment Element dentro de outro iframe porque algumas formas de pagamento exigem o redirecionamento para outra página para confirmação do pagamento. Se você optar por usar um iframe e quiser aceitar Apple Pay ou Google Pay, o iframe deve ter o atributo [permitir](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/iframe#attr-allowpaymentrequest) definido como igual a `"pagamento *"`. O endereço da página de Checkout deve começar com `https://` rather em vez de `http://` for para que sua integração funcione corretamente. Você pode testar sua integração sem usar HTTPS, mas lembre-se de [habilitá-lo](https://docs.stripe.com/security/guide.md#tls) quando estiver pronto para aceitar pagamentos em tempo real. #### HTML + JS ### 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 de Stripe com o seguinte JavaScript em sua página de checkout: ```javascript // Set your publishable key: remember to change this to your live publishable key in production // See your keys here: https://dashboard.stripe.com/apikeys const stripe = Stripe('<>'); ``` ### Adicione o Element Pagamento à sua 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 anterior for carregado, crie uma instância do Payment Element e monte-a no nó DOM do contêiner. Passe o [segredo do cliente](https://docs.stripe.com/api/payment_intents/object.md#payment_intent_object-client_secret) da etapa anterior em `options` quando criar a instância do [Elements](https://docs.stripe.com/js/elements_object/create): Administre cuidadosamente o segredo do cliente, pois ele pode finalizar a cobrança. Não registre em log, incorpore em URLs nem exponha esse segredo a ninguém, exceto para o próprio cliente. ```javascript const options = { clientSecret: '{{CLIENT_SECRET}}', // Fully customizable with appearance API. appearance: {/*...*/}, }; // Set up Stripe.js and Elements to use in checkout form, passing the client secret obtained in a previous stepconst elements = stripe.elements(options); // Create and mount the Payment Element const paymentElementOptions = { layout: 'accordion'}; const paymentElement = elements.create('payment', paymentElementOptions); paymentElement.mount('#payment-element'); ``` #### React ### Configurar 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 ``` ### Adicione e configure o provedor do Elements à sua página de pagamento Para usar o componente Payment Element, encapsule o componente da página de checkout em um [provedor do Elements](https://docs.stripe.com/sdks/stripejs-react.md#elements-provider). Chame `loadStripe` com sua chave publicável e passe a `Promise` retornada para o provedor `Elements`. Além disso, passe o [segredo do cliente](https://docs.stripe.com/api/payment_intents/object.md#payment_intent_object-client_secret) da etapa anterior como `options` ao fornecedor 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('<>'); function App() { const options = { // passing the client secret obtained in step 3 clientSecret: '{{CLIENT_SECRET}}', // Fully customizable with appearance API. appearance: {/*...*/}, }; return ( ); }; ReactDOM.render(, document.getElementById('root')); ``` ### Adicione o componente do Element Pagamento 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 Stripe Elements é uma coleção de componentes drop-in de IU. Para personalizar ainda mais o formulário ou coletar outros dados do cliente, consulte a [documentação do Elements](https://docs.stripe.com/payments/elements.md). O Payment Element renderiza um formulário dinâmico que permite ao cliente escolher uma forma de pagamento. Para cada forma de pagamento, o formulário solicita automaticamente que o cliente preencha todos os dados de pagamento necessários. ### Personalizar a aparência Personalize o Payment Element para corresponder ao design do seu site, passando o [objeto appearance](https://docs.stripe.com/js/elements_object/create#stripe_elements-options-appearance) para `options` ao criar o provedor do `Elements`. ### Solicitar endereços Por padrão, o Payment Element só recolhe os detalhes necessários do endereço de faturamento. Alguns comportamentos, como [calcular impostos](https://docs.stripe.com/api/tax/calculations/create.md) ou inserir detalhes de entrega, exigem o endereço completo do cliente. Você pode: - Use o [Address Element](https://docs.stripe.com/elements/address-element.md) para aproveitar os recursos de autocompletar e traduzir para recolher o endereço completo do cliente. Isso ajuda a garantir um cálculo tributário mais preciso. - Obtenha os detalhes do endereço usando seu próprio formulário personalizado. ### Solicitar token de comerciante do Apple Pay Se você configurou sua integração para [aceitar pagamentos com o Apple Pay](https://docs.stripe.com/payments/accept-a-payment.md?payment-ui=elements&api-integration=checkout), recomendamos configurar a interface do Apple Pay para retornar um token do comerciante, a fim de habilitar transações iniciadas pelo comerciante (MIT). [Solicite o tipo de token do comerciante pertinente](https://docs.stripe.com/apple-pay/merchant-tokens.md?pay-element=web-pe) no Payment Element. ## 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 (
{/* Show error message to your customers */} {errorMessage &&
{errorMessage}
} ); }; 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: Habilite mais formas de pagamento #### Destino Configure formas de pagamento para a sua conta na [página Formas de pagamento](https://dashboard.stripe.com/settings/payment_methods) no Stripe Dashboard. Pagamentos por cartão, Google Pay e Apple Pay estão habilitados por padrão, mas você pode ativar e desativar formas de pagamento conforme a necessidade. Suas contas conectadas não podem personalizar suas próprias formas de pagamento. Antes de exibir o formulário de pagamento a um cliente, 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. O formulário de pagamento prioriza as formas de pagamento que aumentam a conversão e são mais relevantes para a moeda e o local do cliente. As formas de pagamento de prioridade menor ficam ocultas em um menu de navegação. #### Em nome de 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 suspensas para formas de pagamento, cada uma mostrando uma opção disponível (bloqueadas, ativadas por padrão, desativadas por padrão)](https://b.stripecdn.com/docs-statics-srv/assets/dropdowns.ef651d721d5939d81521dd34dde4577f.png) 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. ![Diálogo exibido após clicar no botão Salvar, com uma lista das alterações feitas pelo usuário](https://b.stripecdn.com/docs-statics-srv/assets/dialog.a56ea7716f60db9778706790320d13be.png) 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. ![Captura de tela da caixa de seleção a ser marcada ao permitir que proprietários conectados personalizem formas de pagamento](https://b.stripecdn.com/docs-statics-srv/assets/checkbox.275bd35d2a025272f03af029a144e577.png) 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`. ## Tarifas cobradas Quando um pagamento é processado, em vez de transferir o valor total da transação para uma conta conectada, sua plataforma pode decidir cobrar uma parte do valor da transação na forma de tarifas. Você pode definir os preços das tarifas de duas maneiras diferentes: - Use a [ferramenta de preços da plataforma](https://docs.stripe.com/connect/platform-pricing-tools.md) para definir e testar as regras de preços das tarifas da plataforma. No momento, esse recurso no-code no Stripe Dashboard só está disponível para plataformas responsáveis pelo pagamento das tarifas da Stripe. - Defina internamente as regras de preços, especificando as tarifas diretamente em um [PaymentIntent](https://docs.stripe.com/api/payment_intents/object.md) usando o parâmetro [application_fee_amount](https://docs.stripe.com/api/payment_intents/object.md#payment_intent_object-application_fee_amount) ou [transfer_data[amount]](https://docs.stripe.com/api/payment_intents/object.md#payment_intent_object-transfer_data-amount). As tarifas definidas com esse método substituem a lógica de preços especificada na ferramenta de preços da plataforma. #### application_fee_amount Ao criar cobranças com `application_fee_amount`, o valor total da cobrança é imediatamente transferido da plataforma para a conta `transfer_data[destination]` depois que a cobrança é capturada. O valor `application_fee_amount` (limitado ao valor total da cobrança) é transferido de volta à plataforma em seguida. ```curl curl https://api.stripe.com/v1/payment_intents \ -u "<>:" \ -d amount=1000 \ -d currency=usd \ -d "automatic_payment_methods[enabled]=true" \ -d application_fee_amount=123 \ -d "transfer_data[destination]={{CONNECTEDACCOUNT_ID}}" ``` Depois que a tarifa da plataforma é recolhida, é criado um objeto de [tarifa da plataforma](https://docs.stripe.com/api/application_fees/object.md). Você pode visualizar uma lista de tarifas da plataforma no [Dashboard](https://dashboard.stripe.com/connect/application_fees), com as [tarifas da plataforma](https://docs.stripe.com/api/application_fees/list.md), ou no [Sigma](https://docs.stripe.com/stripe-data/how-sigma-works.md). Você também pode usar a propriedade `amount` no objeto de tarifa da plataforma para relatórios de tarifas discriminadas. Quando usar um `application_fee_amount`, lembre-se: - O `application_fee_amount` é limitado ao valor total da transação. - O `application_fee_amount` é sempre computado na mesma moeda da transação. - A tarifa da plataforma é *liquidada* (When funds are available in your Stripe balance) na mesma moeda de liquidação da conta conectada. Para cobranças de destino internacionais, isso pode [diferir da moeda de liquidação da sua plataforma](https://docs.stripe.com/connect/currencies/fx-quotes-api.md#application-fees-for-destination-charges-and-converting-balances). - Sua plataforma paga a tarifa da Stripe após a transferência do `application_fee_amount` para sua conta. - Nenhuma tarifa da Stripe adicional é aplicada ao valor. - Sua plataforma pode usar relatórios integrados de tarifas da plataforma para reconciliar as [tarifas cobradas](https://dashboard.stripe.com/connect/application_fees). - Em dashboards ou componentes hospedados na Stripe como o [componente de detalhes do pagamento](https://docs.stripe.com/connect/supported-embedded-components/payment-details.md), sua conta conectada pode visualizar o valor total e o valor da tarifa da plataforma. ### Fluxo de fundos com Destination Charges Com o código acima, o valor total da cobrança (US$ 10,00) é adicionado ao saldo pendente da conta conectada. O valor `application_fee_amount` (US$ 1,23) é subtraído do valor da cobrança e transferido para sua plataforma. As tarifas da Stripe (US$ 0,59) são subtraídas do saldo da conta da plataforma. O valor da tarifa da plataforma, deduzido das tarifas da Stripe (US$ 1,23 - US$ 0,59 = US$ 0,64), permanece no saldo da conta da plataforma. ![Fluxo de fundos para Destination Charges](https://b.stripecdn.com/docs-statics-srv/assets/destination_charge_app_fee.c9ef81298155b38f986df02d0efa9167.png) O `application_fee_amount` é disponibilizado no cronograma de transferências normal da conta da plataforma, assim como os fundos das cobranças normais da Stripe. #### transfer_data[amount] O `transfer_data[amount]` é um inteiro positivo que indica o valor da cobrança a ser transferido para `transfer_data[destination]`. Você subtrai as tarifas da plataforma do valor da cobrança e passa o resultado desse cálculo como `transfer_data[amount]`. ```curl curl https://api.stripe.com/v1/payment_intents \ -u "<>:" \ -d amount=1000 \ -d currency=usd \ -d "automatic_payment_methods[enabled]=true" \ -d "transfer_data[amount]=877" \ -d "transfer_data[destination]={{CONNECTEDACCOUNT_ID}}" ``` Ao usar `transfer_data[amount]`, lembre-se: - O valor é limitado ao valor total da transação. - O valor é sempre computado na mesma moeda da transação. - O valor é *liquidado* (When funds are available in your Stripe balance) na [mesma moeda de liquidação da sua plataforma](https://docs.stripe.com/connect/currencies/fx-quotes-api.md#application-fees-for-destination-charges-and-converting-balances). - Nos dashboards hospedados em Stripe ou em componentes como o Stripe Dashboard ou Express Dashboard, sua conta conectada não consegue visualizar o valor total da cobrança. Ela só vê o valor transferido. - Sua plataforma paga separadamente as tarifas da Stripe sobre a cobrança. - Nenhuma tarifa da Stripe adicional é aplicada ao valor. - Para [calcular tarifas](https://docs.stripe.com/stripe-data/query-all-fees-data.md#fees-paid-by-connected-accounts) após a criação de um pagamento, como para fins de relatório, [acesse o PaymentIntent](https://docs.stripe.com/api/payment_intents/retrieve.md) e subtraia o `transfer_data[amount]` do `amount` no PaymentIntent. Considere usar o [valor da tarifa da plataforma](https://docs.stripe.com/connect/destination-charges.md#application-fee) para simplificar a declaração, criando tarifas de plataforma explícitas vinculadas à cobrança. ### Fluxo de fundos Com o código acima, o `amount` da cobrança (US$ 10,00) é adicionado ao saldo da conta da plataforma. O `transfer_data[amount]` (US$ 8,77) é subtraído do saldo da conta da plataforma e adicionado ao saldo pendente da conta conectada. O `amount` da cobrança (US$ 10,00) menos o `transfer_data[amount]` (US$ 8,77) menos as tarifas da Stripe (sobre o `amount` da cobrança), totalizando US$ 0,64, permanece no saldo pendente da conta da plataforma. ![](https://b.stripecdn.com/docs-statics-srv/assets/destination_charge_amount.46cd59f6496607d68020b546aa1af85f.png) O `transfer_data[amount]` é disponibilizado de acordo com o cronograma de transferências normal da conta conectada, da mesma forma que os fundos das cobranças normais da Stripe. As plataformas podem acompanhar o valor retido das cobranças de `transfer_data[amount]` na coluna “Tarifa da plataforma de destino” na exportação do histórico do saldo. ![](https://b.stripecdn.com/docs-statics-srv/assets/ios-overview.9e0d68d009dc005f73a6f5df69e00458.png) 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). 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) Uma [conta configurada pelo cliente](https://docs.stripe.com/api/v2/core/accounts/object.md#v2_account_object-applied_configurations) ou um objeto [Cliente](https://docs.stripe.com/api/customers.md): para configurar uma forma de pagamento para pagamentos futuros, você deve associá-la a um cliente. Crie um objeto para representar seu cliente quando ele criar uma conta na sua empresa. Se o cliente fizer um pagamento como convidado, você poderá criar um objeto `Conta` ou `Cliente` antes do pagamento e associá-lo à sua própria representação interna da conta do cliente posteriormente. 1. (Opcional) [CustomerSession](https://docs.stripe.com/api/customer_sessions.md): os dados do objeto que representa seu cliente são confidenciais e não podem ser recuperados diretamente de um aplicativo. Uma `CustomerSession` concede ao SDK acesso temporário e restrito à `Conta` ou ao `Cliente` e oferece opções de configuração adicionais. Consulte a lista completa de [opções de configuração](https://docs.stripe.com/api/customer_sessions/create.md#create_customer_session-components). > Se você nunca salvar cartões para os clientes e não permitir que clientes recorrentes reutilizem cartões salvos, poderá omitir os objetos `Conta` ou `Cliente` e o objeto `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. Recupera a `Conta` ou o `Cliente` ou cria um novo. 1. Cria uma [CustomerSession](https://docs.stripe.com/api/customer_sessions.md) para a `Conta` ou 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 a [customer_account](https://docs.stripe.com/api/payment_intents/create.md#create_payment_intent-customer_account) ou 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 `PaymentIntent`, o `client_secret` da `CustomerSession`, o ID da `Conta` ou do `Cliente` e sua [chave de publicação](https://dashboard.stripe.com/apikeys) do 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`. #### Accounts v2 #### curl ```bash # Create an Account with the customer configuration (use an existing Account ID if this is a returning customer) curl https://api.stripe.com/v2/core/accounts \ -u <>: \ -X "POST" \ -d "configuration[customer]" # Create a CustomerSession for the Account curl https://api.stripe.com/v1/customer_sessions \ -u <>: \ -X "POST" \ -d "customer_account"="{{CUSTOMER_ACCOUNT_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 <>: \ -X "POST" \ -d "customer_account"="{{CUSTOMER_ACCOUNT_ID}}" \ -d "amount"=1099 \ -d "currency"="eur" \ -d "automatic_payment_methods[enabled]"=true \ -d application_fee_amount="123" \ -d "transfer_data[destination]"="{{CONNECTED_ACCOUNT_ID}}" \ ``` #### Clientes v1 #### 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 <>: \ -X "POST" \ -d "customer"="{{CUSTOMER_ID}}" \ -d "amount"=1099 \ -d "currency"="eur" \ -d "automatic_payment_methods[enabled]"=true \ -d application_fee_amount="123" \ -d "transfer_data[destination]"="{{CONNECTED_ACCOUNT_ID}}" \ ``` #### Listar manualmente as formas de pagamento #### Accounts v2 #### curl ```bash # Create an Account with the customer configuration (use an existing Account ID if this is a returning customer) curl https://api.stripe.com/v2/core/accounts \ -u <>: \ -X "POST" \ -d "configuration[customer]" # Create a CustomerSession for the Account curl https://api.stripe.com/v1/customer_sessions \ -u <>: \ -X "POST" \ -d "customer_account"="{{CUSTOMER_ACCOUNT_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 <>: \ -X "POST" \ -d "customer_account"="{{CUSTOMER_ACCOUNT_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" \ -d "transfer_data[destination]"="{{CONNECTED_ACCOUNT_ID}}" \ ``` #### Clientes v1 #### 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 <>: \ -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" \ -d "transfer_data[destination]"="{{CONNECTED_ACCOUNT_ID}}" \ ``` > 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). #### 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 = publishableKey// 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). ```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 = publishableKey// 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 // 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. ![](https://b.stripecdn.com/docs-statics-srv/assets/xcode.a701d4c1922d19985e9c614a6f105bf1.png) 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 Personalize cores, fontes e assim por diante para combinar com a aparência do seu aplicativo usando a [API appearance](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. ![](https://b.stripecdn.com/docs-statics-srv/assets/ios-mpe-payment-method-layouts.9d0513e2fcec5660378ba1824d952054.png) #### 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. ![](https://b.stripecdn.com/docs-statics-srv/assets/ios-multi-step.cd631ea4f1cd8cf3f39b6b9e1e92b6c5.png) 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: Habilite mais formas de pagamento #### Destino Configure formas de pagamento para a sua conta na [página Formas de pagamento](https://dashboard.stripe.com/settings/payment_methods) no Stripe Dashboard. Pagamentos por cartão, Google Pay e Apple Pay estão habilitados por padrão, mas você pode ativar e desativar formas de pagamento conforme a necessidade. Suas contas conectadas não podem personalizar suas próprias formas de pagamento. Antes de exibir o formulário de pagamento a um cliente, 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. O formulário de pagamento prioriza as formas de pagamento que aumentam a conversão e são mais relevantes para a moeda e o local do cliente. As formas de pagamento de prioridade menor ficam ocultas em um menu de navegação. #### Em nome de 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 suspensas para formas de pagamento, cada uma mostrando uma opção disponível (bloqueadas, ativadas por padrão, desativadas por padrão)](https://b.stripecdn.com/docs-statics-srv/assets/dropdowns.ef651d721d5939d81521dd34dde4577f.png) 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. ![Diálogo exibido após clicar no botão Salvar, com uma lista das alterações feitas pelo usuário](https://b.stripecdn.com/docs-statics-srv/assets/dialog.a56ea7716f60db9778706790320d13be.png) 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. ![Captura de tela da caixa de seleção a ser marcada ao permitir que proprietários conectados personalizem formas de pagamento](https://b.stripecdn.com/docs-statics-srv/assets/checkbox.275bd35d2a025272f03af029a144e577.png) 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`. ## Tarifas cobradas Quando um pagamento é processado, em vez de transferir o valor total da transação para uma conta conectada, sua plataforma pode decidir cobrar uma parte do valor da transação na forma de tarifas. Você pode definir os preços das tarifas de duas maneiras diferentes: - Use a [ferramenta de preços da plataforma](https://docs.stripe.com/connect/platform-pricing-tools.md) para definir e testar as regras de preços das tarifas da plataforma. No momento, esse recurso no-code no Stripe Dashboard só está disponível para plataformas responsáveis pelo pagamento das tarifas da Stripe. - Defina internamente as regras de preços, especificando as tarifas diretamente em um [PaymentIntent](https://docs.stripe.com/api/payment_intents/object.md) usando o parâmetro [application_fee_amount](https://docs.stripe.com/api/payment_intents/object.md#payment_intent_object-application_fee_amount) ou [transfer_data[amount]](https://docs.stripe.com/api/payment_intents/object.md#payment_intent_object-transfer_data-amount). As tarifas definidas com esse método substituem a lógica de preços especificada na ferramenta de preços da plataforma. #### application_fee_amount Ao criar cobranças com `application_fee_amount`, o valor total da cobrança é imediatamente transferido da plataforma para a conta `transfer_data[destination]` depois que a cobrança é capturada. O valor `application_fee_amount` (limitado ao valor total da cobrança) é transferido de volta à plataforma em seguida. ```curl curl https://api.stripe.com/v1/payment_intents \ -u "<>:" \ -d amount=1000 \ -d currency=usd \ -d "automatic_payment_methods[enabled]=true" \ -d application_fee_amount=123 \ -d "transfer_data[destination]={{CONNECTEDACCOUNT_ID}}" ``` Depois que a tarifa da plataforma é recolhida, é criado um objeto de [tarifa da plataforma](https://docs.stripe.com/api/application_fees/object.md). Você pode visualizar uma lista de tarifas da plataforma no [Dashboard](https://dashboard.stripe.com/connect/application_fees), com as [tarifas da plataforma](https://docs.stripe.com/api/application_fees/list.md), ou no [Sigma](https://docs.stripe.com/stripe-data/how-sigma-works.md). Você também pode usar a propriedade `amount` no objeto de tarifa da plataforma para relatórios de tarifas discriminadas. Quando usar um `application_fee_amount`, lembre-se: - O `application_fee_amount` é limitado ao valor total da transação. - O `application_fee_amount` é sempre computado na mesma moeda da transação. - A tarifa da plataforma é *liquidada* (When funds are available in your Stripe balance) na mesma moeda de liquidação da conta conectada. Para cobranças de destino internacionais, isso pode [diferir da moeda de liquidação da sua plataforma](https://docs.stripe.com/connect/currencies/fx-quotes-api.md#application-fees-for-destination-charges-and-converting-balances). - Sua plataforma paga a tarifa da Stripe após a transferência do `application_fee_amount` para sua conta. - Nenhuma tarifa da Stripe adicional é aplicada ao valor. - Sua plataforma pode usar relatórios integrados de tarifas da plataforma para reconciliar as [tarifas cobradas](https://dashboard.stripe.com/connect/application_fees). - Em dashboards ou componentes hospedados na Stripe como o [componente de detalhes do pagamento](https://docs.stripe.com/connect/supported-embedded-components/payment-details.md), sua conta conectada pode visualizar o valor total e o valor da tarifa da plataforma. ### Fluxo de fundos com Destination Charges Com o código acima, o valor total da cobrança (US$ 10,00) é adicionado ao saldo pendente da conta conectada. O valor `application_fee_amount` (US$ 1,23) é subtraído do valor da cobrança e transferido para sua plataforma. As tarifas da Stripe (US$ 0,59) são subtraídas do saldo da conta da plataforma. O valor da tarifa da plataforma, deduzido das tarifas da Stripe (US$ 1,23 - US$ 0,59 = US$ 0,64), permanece no saldo da conta da plataforma. ![Fluxo de fundos para Destination Charges](https://b.stripecdn.com/docs-statics-srv/assets/destination_charge_app_fee.c9ef81298155b38f986df02d0efa9167.png) O `application_fee_amount` é disponibilizado no cronograma de transferências normal da conta da plataforma, assim como os fundos das cobranças normais da Stripe. #### transfer_data[amount] O `transfer_data[amount]` é um inteiro positivo que indica o valor da cobrança a ser transferido para `transfer_data[destination]`. Você subtrai as tarifas da plataforma do valor da cobrança e passa o resultado desse cálculo como `transfer_data[amount]`. ```curl curl https://api.stripe.com/v1/payment_intents \ -u "<>:" \ -d amount=1000 \ -d currency=usd \ -d "automatic_payment_methods[enabled]=true" \ -d "transfer_data[amount]=877" \ -d "transfer_data[destination]={{CONNECTEDACCOUNT_ID}}" ``` Ao usar `transfer_data[amount]`, lembre-se: - O valor é limitado ao valor total da transação. - O valor é sempre computado na mesma moeda da transação. - O valor é *liquidado* (When funds are available in your Stripe balance) na [mesma moeda de liquidação da sua plataforma](https://docs.stripe.com/connect/currencies/fx-quotes-api.md#application-fees-for-destination-charges-and-converting-balances). - Nos dashboards hospedados em Stripe ou em componentes como o Stripe Dashboard ou Express Dashboard, sua conta conectada não consegue visualizar o valor total da cobrança. Ela só vê o valor transferido. - Sua plataforma paga separadamente as tarifas da Stripe sobre a cobrança. - Nenhuma tarifa da Stripe adicional é aplicada ao valor. - Para [calcular tarifas](https://docs.stripe.com/stripe-data/query-all-fees-data.md#fees-paid-by-connected-accounts) após a criação de um pagamento, como para fins de relatório, [acesse o PaymentIntent](https://docs.stripe.com/api/payment_intents/retrieve.md) e subtraia o `transfer_data[amount]` do `amount` no PaymentIntent. Considere usar o [valor da tarifa da plataforma](https://docs.stripe.com/connect/destination-charges.md#application-fee) para simplificar a declaração, criando tarifas de plataforma explícitas vinculadas à cobrança. ### Fluxo de fundos Com o código acima, o `amount` da cobrança (US$ 10,00) é adicionado ao saldo da conta da plataforma. O `transfer_data[amount]` (US$ 8,77) é subtraído do saldo da conta da plataforma e adicionado ao saldo pendente da conta conectada. O `amount` da cobrança (US$ 10,00) menos o `transfer_data[amount]` (US$ 8,77) menos as tarifas da Stripe (sobre o `amount` da cobrança), totalizando US$ 0,64, permanece no saldo pendente da conta da plataforma. ![](https://b.stripecdn.com/docs-statics-srv/assets/destination_charge_amount.46cd59f6496607d68020b546aa1af85f.png) O `transfer_data[amount]` é disponibilizado de acordo com o cronograma de transferências normal da conta conectada, da mesma forma que os fundos das cobranças normais da Stripe. As plataformas podem acompanhar o valor retido das cobranças de `transfer_data[amount]` na coluna “Tarifa da plataforma de destino” na exportação do histórico do saldo. ![](https://b.stripecdn.com/docs-statics-srv/assets/android-overview.471eaf89a760f5b6a757fd96b6bb9b60.png) 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.3.0") // Include the financial connections SDK to support US bank account as a payment method implementation("com.stripe:financial-connections:23.3.0") } ``` > 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). 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) Uma [conta configurada pelo cliente](https://docs.stripe.com/api/v2/core/accounts/object.md#v2_account_object-applied_configurations) ou um objeto [Cliente](https://docs.stripe.com/api/customers.md): para configurar uma forma de pagamento para pagamentos futuros, você deve associá-la a um cliente. Crie um objeto para representar seu cliente quando ele criar uma conta na sua empresa. Se o cliente fizer um pagamento como convidado, você poderá criar um objeto `Conta` ou `Cliente` antes do pagamento e associá-lo à sua própria representação interna da conta do cliente posteriormente. 1. (Opcional) [CustomerSession](https://docs.stripe.com/api/customer_sessions.md): os dados do objeto que representa seu cliente são confidenciais e não podem ser recuperados diretamente de um aplicativo. Uma `CustomerSession` concede ao SDK acesso temporário e restrito à `Conta` ou ao `Cliente` e oferece opções de configuração adicionais. Consulte a lista completa de [opções de configuração](https://docs.stripe.com/api/customer_sessions/create.md#create_customer_session-components). > Se você nunca salvar cartões para os clientes e não permitir que clientes recorrentes reutilizem cartões salvos, poderá omitir os objetos `Conta` ou `Cliente` e o objeto `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. Recupera a `Conta` ou o `Cliente` ou cria um novo. 1. Cria uma [CustomerSession](https://docs.stripe.com/api/customer_sessions.md) para a `Conta` ou 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 a [customer_account](https://docs.stripe.com/api/payment_intents/create.md#create_payment_intent-customer_account) ou 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 `PaymentIntent`, o `client_secret` da `CustomerSession`, o ID da `Conta` ou do `Cliente` e sua [chave de publicação](https://dashboard.stripe.com/apikeys) do 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`. #### Accounts v2 #### curl ```bash # Create an Account with the customer configuration (use an existing Account ID if this is a returning customer) curl https://api.stripe.com/v2/core/accounts \ -u <>: \ -X "POST" \ -d "configuration[customer]" # Create a CustomerSession for the Account curl https://api.stripe.com/v1/customer_sessions \ -u <>: \ -X "POST" \ -d "customer_account"="{{CUSTOMER_ACCOUNT_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 <>: \ -X "POST" \ -d "customer_account"="{{CUSTOMER_ACCOUNT_ID}}" \ -d "amount"=1099 \ -d "currency"="eur" \ -d "automatic_payment_methods[enabled]"=true \ -d application_fee_amount="123" \ -d "transfer_data[destination]"="{{CONNECTED_ACCOUNT_ID}}" \ ``` #### Clientes v1 #### 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 <>: \ -X "POST" \ -d "customer"="{{CUSTOMER_ID}}" \ -d "amount"=1099 \ -d "currency"="eur" \ -d "automatic_payment_methods[enabled]"=true \ -d application_fee_amount="123" \ -d "transfer_data[destination]"="{{CONNECTED_ACCOUNT_ID}}" \ ``` #### Listar manualmente as formas de pagamento #### Accounts v2 #### curl ```bash # Create an Account with the customer configuration (use an existing Account ID if this is a returning customer) curl https://api.stripe.com/v2/core/accounts \ -u <>: \ -X "POST" \ -d "configuration[customer]" # Create a CustomerSession for the Account curl https://api.stripe.com/v1/customer_sessions \ -u <>: \ -X "POST" \ -d "customer_account"="{{CUSTOMER_ACCOUNT_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 <>: \ -X "POST" \ -d "customer_account"="{{CUSTOMER_ACCOUNT_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" \ -d "transfer_data[destination]"="{{CONNECTED_ACCOUNT_ID}}" \ ``` #### Clientes v1 #### 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 <>: \ -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" \ -d "transfer_data[destination]"="{{CONNECTED_ACCOUNT_ID}}" \ ``` > 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)} } } 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) } }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)} } } 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 Personalize cores, fontes e assim por diante para combinar com a aparência do seu aplicativo usando a [API appearance](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. ![](https://b.stripecdn.com/docs-statics-srv/assets/android-mpe-payment-method-layouts.3bcfe828ceaad1a94e0572a22d91733f.png) #### 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. ![](https://b.stripecdn.com/docs-statics-srv/assets/android-multi-step.84d8a0a44b1baa596bda491322b6d9fd.png) > 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: Habilite mais formas de pagamento #### Destino Configure formas de pagamento para a sua conta na [página Formas de pagamento](https://dashboard.stripe.com/settings/payment_methods) no Stripe Dashboard. Pagamentos por cartão, Google Pay e Apple Pay estão habilitados por padrão, mas você pode ativar e desativar formas de pagamento conforme a necessidade. Suas contas conectadas não podem personalizar suas próprias formas de pagamento. Antes de exibir o formulário de pagamento a um cliente, 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. O formulário de pagamento prioriza as formas de pagamento que aumentam a conversão e são mais relevantes para a moeda e o local do cliente. As formas de pagamento de prioridade menor ficam ocultas em um menu de navegação. #### Em nome de 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 suspensas para formas de pagamento, cada uma mostrando uma opção disponível (bloqueadas, ativadas por padrão, desativadas por padrão)](https://b.stripecdn.com/docs-statics-srv/assets/dropdowns.ef651d721d5939d81521dd34dde4577f.png) 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. ![Diálogo exibido após clicar no botão Salvar, com uma lista das alterações feitas pelo usuário](https://b.stripecdn.com/docs-statics-srv/assets/dialog.a56ea7716f60db9778706790320d13be.png) 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. ![Captura de tela da caixa de seleção a ser marcada ao permitir que proprietários conectados personalizem formas de pagamento](https://b.stripecdn.com/docs-statics-srv/assets/checkbox.275bd35d2a025272f03af029a144e577.png) 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`. ## Tarifas cobradas Quando um pagamento é processado, em vez de transferir o valor total da transação para uma conta conectada, sua plataforma pode decidir cobrar uma parte do valor da transação na forma de tarifas. Você pode definir os preços das tarifas de duas maneiras diferentes: - Use a [ferramenta de preços da plataforma](https://docs.stripe.com/connect/platform-pricing-tools.md) para definir e testar as regras de preços das tarifas da plataforma. No momento, esse recurso no-code no Stripe Dashboard só está disponível para plataformas responsáveis pelo pagamento das tarifas da Stripe. - Defina internamente as regras de preços, especificando as tarifas diretamente em um [PaymentIntent](https://docs.stripe.com/api/payment_intents/object.md) usando o parâmetro [application_fee_amount](https://docs.stripe.com/api/payment_intents/object.md#payment_intent_object-application_fee_amount) ou [transfer_data[amount]](https://docs.stripe.com/api/payment_intents/object.md#payment_intent_object-transfer_data-amount). As tarifas definidas com esse método substituem a lógica de preços especificada na ferramenta de preços da plataforma. #### application_fee_amount Ao criar cobranças com `application_fee_amount`, o valor total da cobrança é imediatamente transferido da plataforma para a conta `transfer_data[destination]` depois que a cobrança é capturada. O valor `application_fee_amount` (limitado ao valor total da cobrança) é transferido de volta à plataforma em seguida. ```curl curl https://api.stripe.com/v1/payment_intents \ -u "<>:" \ -d amount=1000 \ -d currency=usd \ -d "automatic_payment_methods[enabled]=true" \ -d application_fee_amount=123 \ -d "transfer_data[destination]={{CONNECTEDACCOUNT_ID}}" ``` Depois que a tarifa da plataforma é recolhida, é criado um objeto de [tarifa da plataforma](https://docs.stripe.com/api/application_fees/object.md). Você pode visualizar uma lista de tarifas da plataforma no [Dashboard](https://dashboard.stripe.com/connect/application_fees), com as [tarifas da plataforma](https://docs.stripe.com/api/application_fees/list.md), ou no [Sigma](https://docs.stripe.com/stripe-data/how-sigma-works.md). Você também pode usar a propriedade `amount` no objeto de tarifa da plataforma para relatórios de tarifas discriminadas. Quando usar um `application_fee_amount`, lembre-se: - O `application_fee_amount` é limitado ao valor total da transação. - O `application_fee_amount` é sempre computado na mesma moeda da transação. - A tarifa da plataforma é *liquidada* (When funds are available in your Stripe balance) na mesma moeda de liquidação da conta conectada. Para cobranças de destino internacionais, isso pode [diferir da moeda de liquidação da sua plataforma](https://docs.stripe.com/connect/currencies/fx-quotes-api.md#application-fees-for-destination-charges-and-converting-balances). - Sua plataforma paga a tarifa da Stripe após a transferência do `application_fee_amount` para sua conta. - Nenhuma tarifa da Stripe adicional é aplicada ao valor. - Sua plataforma pode usar relatórios integrados de tarifas da plataforma para reconciliar as [tarifas cobradas](https://dashboard.stripe.com/connect/application_fees). - Em dashboards ou componentes hospedados na Stripe como o [componente de detalhes do pagamento](https://docs.stripe.com/connect/supported-embedded-components/payment-details.md), sua conta conectada pode visualizar o valor total e o valor da tarifa da plataforma. ### Fluxo de fundos com Destination Charges Com o código acima, o valor total da cobrança (US$ 10,00) é adicionado ao saldo pendente da conta conectada. O valor `application_fee_amount` (US$ 1,23) é subtraído do valor da cobrança e transferido para sua plataforma. As tarifas da Stripe (US$ 0,59) são subtraídas do saldo da conta da plataforma. O valor da tarifa da plataforma, deduzido das tarifas da Stripe (US$ 1,23 - US$ 0,59 = US$ 0,64), permanece no saldo da conta da plataforma. ![Fluxo de fundos para Destination Charges](https://b.stripecdn.com/docs-statics-srv/assets/destination_charge_app_fee.c9ef81298155b38f986df02d0efa9167.png) O `application_fee_amount` é disponibilizado no cronograma de transferências normal da conta da plataforma, assim como os fundos das cobranças normais da Stripe. #### transfer_data[amount] O `transfer_data[amount]` é um inteiro positivo que indica o valor da cobrança a ser transferido para `transfer_data[destination]`. Você subtrai as tarifas da plataforma do valor da cobrança e passa o resultado desse cálculo como `transfer_data[amount]`. ```curl curl https://api.stripe.com/v1/payment_intents \ -u "<>:" \ -d amount=1000 \ -d currency=usd \ -d "automatic_payment_methods[enabled]=true" \ -d "transfer_data[amount]=877" \ -d "transfer_data[destination]={{CONNECTEDACCOUNT_ID}}" ``` Ao usar `transfer_data[amount]`, lembre-se: - O valor é limitado ao valor total da transação. - O valor é sempre computado na mesma moeda da transação. - O valor é *liquidado* (When funds are available in your Stripe balance) na [mesma moeda de liquidação da sua plataforma](https://docs.stripe.com/connect/currencies/fx-quotes-api.md#application-fees-for-destination-charges-and-converting-balances). - Nos dashboards hospedados em Stripe ou em componentes como o Stripe Dashboard ou Express Dashboard, sua conta conectada não consegue visualizar o valor total da cobrança. Ela só vê o valor transferido. - Sua plataforma paga separadamente as tarifas da Stripe sobre a cobrança. - Nenhuma tarifa da Stripe adicional é aplicada ao valor. - Para [calcular tarifas](https://docs.stripe.com/stripe-data/query-all-fees-data.md#fees-paid-by-connected-accounts) após a criação de um pagamento, como para fins de relatório, [acesse o PaymentIntent](https://docs.stripe.com/api/payment_intents/retrieve.md) e subtraia o `transfer_data[amount]` do `amount` no PaymentIntent. Considere usar o [valor da tarifa da plataforma](https://docs.stripe.com/connect/destination-charges.md#application-fee) para simplificar a declaração, criando tarifas de plataforma explícitas vinculadas à cobrança. ### Fluxo de fundos Com o código acima, o `amount` da cobrança (US$ 10,00) é adicionado ao saldo da conta da plataforma. O `transfer_data[amount]` (US$ 8,77) é subtraído do saldo da conta da plataforma e adicionado ao saldo pendente da conta conectada. O `amount` da cobrança (US$ 10,00) menos o `transfer_data[amount]` (US$ 8,77) menos as tarifas da Stripe (sobre o `amount` da cobrança), totalizando US$ 0,64, permanece no saldo pendente da conta da plataforma. ![](https://b.stripecdn.com/docs-statics-srv/assets/destination_charge_amount.46cd59f6496607d68020b546aa1af85f.png) O `transfer_data[amount]` é disponibilizado de acordo com o cronograma de transferências normal da conta conectada, da mesma forma que os fundos das cobranças normais da Stripe. As plataformas podem acompanhar o valor retido das cobranças de `transfer_data[amount]` na coluna “Tarifa da plataforma de destino” na exportação do histórico do saldo. ![](https://b.stripecdn.com/docs-statics-srv/assets/ios-overview.9e0d68d009dc005f73a6f5df69e00458.png) 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. > Recomendamos seguir o [guia oficial do TypeScript](https://reactnative.dev/docs/typescript#adding-typescript-to-an-existing-project) para adicionar suporte ao TypeScript. ### 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 da API publicável](https://docs.stripe.com/keys.md#obtain-api-keys) em `publishableKey` é necessária. O exemplo a seguir mostra como inicializar a Stripe usando o componente `StripeProvider`. ```jsx import { useState, useEffect } from 'react'; import { StripeProvider } from '@stripe/stripe-react-native'; function App() { const [publishableKey, setPublishableKey] = useState(''); const fetchPublishableKey = async () => { const key = await fetchKey(); // fetch key from your server here setPublishableKey(key); }; useEffect(() => { fetchPublishableKey(); }, []); 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 de [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). 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) Uma [conta configurada pelo cliente](https://docs.stripe.com/api/v2/core/accounts/object.md#v2_account_object-applied_configurations) ou um objeto [Cliente](https://docs.stripe.com/api/customers.md): para configurar uma forma de pagamento para pagamentos futuros, você deve associá-la a um cliente. Crie um objeto para representar seu cliente quando ele criar uma conta na sua empresa. Se o cliente fizer um pagamento como convidado, você poderá criar um objeto `Conta` ou `Cliente` antes do pagamento e associá-lo à sua própria representação interna da conta do cliente posteriormente. 1. (Opcional) [CustomerSession](https://docs.stripe.com/api/customer_sessions.md): os dados do objeto que representa seu cliente são confidenciais e não podem ser recuperados diretamente de um aplicativo. Uma `CustomerSession` concede ao SDK acesso temporário e restrito à `Conta` ou ao `Cliente` e oferece opções de configuração adicionais. Consulte a lista completa de [opções de configuração](https://docs.stripe.com/api/customer_sessions/create.md#create_customer_session-components). > Se você nunca salvar cartões para os clientes e não permitir que clientes recorrentes reutilizem cartões salvos, poderá omitir os objetos `Conta` ou `Cliente` e o objeto `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. Recupera a `Conta` ou o `Cliente` ou cria um novo. 1. Cria uma [CustomerSession](https://docs.stripe.com/api/customer_sessions.md) para a `Conta` ou 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 a [customer_account](https://docs.stripe.com/api/payment_intents/create.md#create_payment_intent-customer_account) ou 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 `PaymentIntent`, o `client_secret` da `CustomerSession`, o ID da `Conta` ou do `Cliente` e sua [chave de publicação](https://dashboard.stripe.com/apikeys) do 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`. #### Accounts v2 #### curl ```bash # Create an Account with the customer configuration (use an existing Account ID if this is a returning customer) curl https://api.stripe.com/v2/core/accounts \ -u <>: \ -X "POST" \ -d "configuration[customer]" # Create a CustomerSession for the Account curl https://api.stripe.com/v1/customer_sessions \ -u <>: \ -X "POST" \ -d "customer_account"="{{CUSTOMER_ACCOUNT_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 <>: \ -X "POST" \ -d "customer_account"="{{CUSTOMER_ACCOUNT_ID}}" \ -d "amount"=1099 \ -d "currency"="eur" \ -d "automatic_payment_methods[enabled]"=true \ -d application_fee_amount="123" \ -d "transfer_data[destination]"="{{CONNECTED_ACCOUNT_ID}}" \ ``` #### Clientes v1 #### 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 <>: \ -X "POST" \ -d "customer"="{{CUSTOMER_ID}}" \ -d "amount"=1099 \ -d "currency"="eur" \ -d "automatic_payment_methods[enabled]"=true \ -d application_fee_amount="123" \ -d "transfer_data[destination]"="{{CONNECTED_ACCOUNT_ID}}" \ ``` #### Listar manualmente as formas de pagamento #### Accounts v2 #### curl ```bash # Create an Account with the customer configuration (use an existing Account ID if this is a returning customer) curl https://api.stripe.com/v2/core/accounts \ -u <>: \ -X "POST" \ -d "configuration[customer]" # Create a CustomerSession for the Account curl https://api.stripe.com/v1/customer_sessions \ -u <>: \ -X "POST" \ -d "customer_account"="{{CUSTOMER_ACCOUNT_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 <>: \ -X "POST" \ -d "customer_account"="{{CUSTOMER_ACCOUNT_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" \ -d "transfer_data[destination]"="{{CONNECTED_ACCOUNT_ID}}" \ ``` #### Clientes v1 #### 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 <>: \ -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" \ -d "transfer_data[destination]"="{{CONNECTED_ACCOUNT_ID}}" \ ``` > 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`. #### Accounts v2 ```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_account } = await response.json(); return { paymentIntent, ephemeralKey, customer_account, }; }; const initializePaymentSheet = async () => { const { paymentIntent, ephemeralKey, customer_account, } = await fetchPaymentSheetParams(); const { error } = await initPaymentSheet({ merchantDisplayName: "Example, Inc.", customerAccountId: customer_account, customerEphemeralKeySecret: ephemeralKey, paymentIntentClientSecret: paymentIntent, // Set `allowsDelayedPaymentMethods` to true if your business accepts 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 (