# Criar cobranças e transferências separadas Crie cobranças na conta da sua plataforma e transfira fundos para várias contas conectadas. Instruções para LLMs: com frequência, a Stripe lança novos produtos e recursos. Veja as práticas recomendadas da Stripe em https://raw.githubusercontent.com/stripe/ai/refs/heads/main/skills/stripe-best-practices/SKILL.md antes da implementação. Crie *cobranças e transferências separadas* para transferir fundos de um pagamento para várias contas conectadas ou quando um usuário específico não for conhecido no momento do pagamento. A cobrança na conta da sua plataforma é desvinculada das transferências para suas contas conectadas. Com este tipo de cobrança: - Você cria uma cobrança na conta da sua plataforma e transfere fundos para suas contas conectadas. O pagamento aparece como cobrança na sua conta, e também há transferências para contas conectadas (valor determinado por você), que são retiradas do saldo da sua conta. - Você pode transferir os fundos para diferentes contas conectadas. - O custo das tarifas da Stripe e de reembolsos ou estornos é debitado da sua conta. Esse tipo de cobrança ajuda os marketplaces a dividir os pagamentos entre várias partes. Por exemplo, uma plataforma de entrega de restaurantes que divide os pagamentos entre o restaurante e o entregador. > A segregação de fundos é um recurso de visualização privada que mantém os fundos de pagamento em um estado de retenção protegido antes de você transferi-los para contas conectadas. Isso evita que os fundos alocados sejam usados para operações não relacionadas à plataforma. Entre em contato com seu gerente da conta Stripe para solicitar acesso. A Stripe aceita cobranças e transferências separadas nas seguintes regiões: - AT - AU - BE - BG - BR - CA - CH - CY - CZ - DE - DK - EE - ES - FI - FR - GB - GR - HR - HU - IE - IT - JP - LI - LT - LU - LV - MT - MX - MY - NL - NO - NZ - PL - PT - RO - SE - SG - SI - SK - US ## Transferências transfronteiriças A Stripe oferece suporte a transferências transfronteiriças no saldo de pagamentos entre os Estados Unidos, o Canadá, O Reino Unido, o EEE e a Suíça. Em outros cenários, a plataforma e qualquer conta conectada precisam estar na mesma região. Tentar transferir fundos entre fronteiras ou saldos não compatíveis retorna um erro. Consulte [pagamentos transfronteiriços](https://docs.stripe.com/connect/cross-border-payouts.md) para fluxos de fundos compatíveis entre outras regiões. Você deve usar transferências apenas em combinação com os casos de uso permitidos para [cobranças](https://docs.stripe.com/connect/charges.md), [recargas](https://docs.stripe.com/connect/top-ups.md) e [tarifas](https://docs.stripe.com/connect/separate-charges-and-transfers.md#collect-fees). Recomendamos usar cobranças e transferências separadas somente quando você for responsável por saldos negativos das suas contas conectadas. Redirecione para uma página de pagamento hospedada pela Stripe usando o [Stripe Checkout](https://docs.stripe.com/payments/checkout.md). Veja como essa integração [se compara a outros tipos 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 [Checkout Session](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 e a moeda do pedido, bem como formas de pagamento aceitáveis. Adicione um botão de checkout ao seu site para chamar um endpoint do lado do servidor e criar uma Sessão do Checkout. ```html Checkout
``` No seu servidor, crie uma sessão do Checkout e redirecione o cliente para o [URL](https://docs.stripe.com/api/checkout/sessions/object.md#checkout_session_object-url) retornado na resposta. ```curl curl https://api.stripe.com/v1/checkout/sessions \ -u "<>:" \ -d "line_items[0][price_data][currency]"=usd \ -d "line_items[0][price_data][product_data][name]"="Restaurant delivery service" \ -d "line_items[0][price_data][unit_amount]"=10000 \ -d "line_items[0][quantity]"=1 \ -d "payment_intent_data[transfer_group]"=ORDER100 \ -d mode=payment \ --data-urlencode success_url="https://example.com/success?session_id={CHECKOUT_SESSION_ID}" ``` - `line_items` – este atributo representa os itens que o cliente está comprando. Os itens são exibidos na página de checkout hospedada pela Stripe. - `payment_intent_data[transfer_group]` – use uma string exclusiva como `transfer_group` para identificar objetos associados entre si. Quando a Stripe cria automaticamente uma cobrança para uma PaymentIntent com um valor de `transfer_group`, atribui o mesmo valor ao `transfer_group` da cobrança. - `success_url` - A Stripe redireciona o cliente para o URL de êxito após a conclusão de um pagamento e substitui a string `{CHECKOUT_SESSION_ID}` pelo ID da sessão do Checkout. Use isso para acessar a sessão do Checkout e inspecionar o status para decidir o que mostrar ao cliente. Você também pode anexar seus próprios parâmetros de consulta, que permanecem durante o processo de redirecionamento. Consulte [personalizar o comportamento de redirecionamento com uma página hospedada pela Stripe](https://docs.stripe.com/payments/checkout/custom-success-page.md) para saber mais. (See full diagram at https://docs.stripe.com/connect/separate-charges-and-transfers) ## 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. ## Criar uma transferência [Lado do servidor] No seu servidor, envie fundos da sua conta para uma conta conectada criando uma [Transferência](https://docs.stripe.com/api/transfers/create.md) e especificando o `transfer_group` utilizado. ```curl curl https://api.stripe.com/v1/transfers \ -u "<>:" \ -d amount=7000 \ -d currency=usd \ -d destination="{{CONNECTEDACCOUNT_ID}}" \ -d transfer_group=ORDER100 ``` Os valores de transferência e cobrança não precisam ser iguais. Você pode dividir uma única cobrança entre várias transferências ou incluir várias cobranças em uma única transferência. O exemplo a seguir cria uma transferência adicional associada ao mesmo `transfer_group`. ```curl curl https://api.stripe.com/v1/transfers \ -u "<>:" \ -d amount=2000 \ -d currency=usd \ -d destination={{OTHER_CONNECTED_ACCOUNT_ID}} \ -d transfer_group=ORDER100 ``` ### Opções de transferência Você pode atribuir qualquer valor à string `transfer_group`, mas ela deve representar uma única ação de negócios. Também é possível fazer uma transferência sem associar uma cobrança ou `transfer_group`. Por exemplo, quando você paga um provedor, mas não há um pagamento a cliente associado. > O `transfer_group` identifica apenas objetos associados. Ele não afeta nenhuma funcionalidade padrão. Para evitar que uma transferência seja executada antes que os fundos da cobrança associada estejam disponíveis, use o atributo `source_transaction` da transferência. Por padrão, uma solicitação de transferência falha quando o valor excede o [saldo da conta disponível](https://docs.stripe.com/connect/account-balances.md) da plataforma. A Stripe não repete automaticamente solicitações de transferência malsucedidas. Você pode evitar falhas nas solicitações de transferência para transferências associadas a cobranças. Quando você especifica a cobrança associada [como a source_transaction da transferência](https://docs.stripe.com/connect/separate-charges-and-transfers.md#transfer-availability), a solicitação de transferência é bem-sucedida automaticamente. No entanto, não executamos a transferência até que os fundos dessa cobrança estejam disponíveis na conta da plataforma. > Se você usa cobranças e transferências separadas, leve isso em consideração quando planejar seu cronograma de repasses *payout* (A payout is the transfer of funds to an external account, usually a bank account, in the form of a deposit). Repasses automáticos podem interferir nas transferências que não têm uma `source_transaction` definida. ### Formas de pagamento assíncronas Se você estiver usando *formas de pagamento assíncronas* (Asynchronous payment methods can take up to several days to confirm whether the payment has been successful. During this time, the payment can't be guaranteed) (como débito ACH ou débito SEPA), aguarde um evento [charge.succeeded](https://docs.stripe.com/api/events/types.md#event_types-charge.succeeded) antes de criar uma transferência. Ao contrário das cobranças de destino, a Stripe não reverte automaticamente uma transferência se o pagamento assíncrono associado falhar. Se você criar uma transferência e o pagamento falhar posteriormente, o saldo da sua plataforma será debitado pelo valor da transferência. Você deverá então [reverter manualmente a transferência](https://docs.stripe.com/connect/separate-charges-and-transfers.md#reverse-transfers) para recuperar os fundos. ## Teste a integração #### Cartões | Número do cartão | Cenário | Como testar | | ------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------- | | 4242424242424242 | O pagamento com cartão é bem-sucedido e não precisa de autenticação. | Preencha o formulário do cartão de crédito usando o número do cartão de crédito com qualquer validade, CVC e código postal. | | 4000002500003155 | O pagamento com cartão precisa de *autenticação* (Strong Customer Authentication (SCA) is a regulatory requirement in effect as of September 14, 2019, that impacts many European online payments. It requires customers to use two-factor authentication like 3D Secure to verify their purchase). | Preencha o formulário do cartão de crédito usando o número do cartão de crédito com qualquer validade, CVC e código postal. | | 4000000000009995 | O cartão é recusado com um código de recusa como `insufficient_funds`. | Preencha o formulário do cartão de crédito usando o número do cartão de crédito com qualquer validade, CVC e código postal. | | 6205500000000000004 | O cartão UnionPay tem um comprimento variável de 13 a 19 dígitos. | Preencha o formulário do cartão de crédito usando o número do cartão de crédito com qualquer validade, CVC e código postal. | #### Carteiras | Forma de pagamento | Cenário | Como testar | | ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Alipay | O cliente paga com uma forma de pagamento baseada em redirecionamento e [notificação imediata](https://docs.stripe.com/payments/payment-methods.md#payment-notification). | Escolha qualquer forma de pagamento baseada em redirecionamento, preencha os dados obrigatórios e confirme o pagamento. Em seguida, clique em **Concluir o pagamento de teste** na página de redirecionamento. | #### Débito bancário autenticado | Forma de pagamento | Cenário | Como testar | | ------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Débito automático BECS | O cliente paga com débito automático BECS. | Preencha o formulário usando o número de conta `900123456` e BSB `000000`. Inicialmente, o status do PaymentIntent muda para `processing` e, 3 minutos depois, para `succeeded`. | | Débito automático BECS | O pagamento do cliente falha com um código de erro `account_closed`. | Preencha o formulário usando o número da conta `111111113` e BSB `000000`. | | Bancontact, EPS, iDEAL, e Przelewy24 | Seu cliente não faz a autenticação na página de redirecionamento de uma forma de pagamento baseada em redirecionamento e notificação imediata. | Escolha qualquer forma de pagamento baseada em redirecionamento, preencha os dados obrigatórios e confirme o pagamento. Em seguida, clique em **Falhar pagamento de teste** na página de redirecionamento. | | Pay by Bank | O cliente paga com uma forma de pagamento baseada em redirecionamento e [notificação posterior](https://docs.stripe.com/payments/payment-methods.md#payment-notification). | Escolha a forma de pagamento, preencha os dados obrigatórios e confirme o pagamento. Em seguida, clique em **Concluir o pagamento de teste** na página de redirecionamento. | | Pay by Bank | Seu cliente não faz a autenticação na página de redirecionamento de uma forma de pagamento baseada em redirecionamento e notificação posterior. | Escolha a forma de pagamento, preencha os dados obrigatórios e confirme o pagamento. Em seguida, clique em **Falhar o pagamento de teste** na página de redirecionamento. | | BLIK | Os pagamentos BLIK falham de várias formas: falhas imediatas (por exemplo, o código está vencido ou inválido), erros atrasados (o banco recusa) ou limites de tempo (o cliente não respondeu a tempo). | Use padrões de e-mail para [simular as diferentes falhas.](https://docs.stripe.com/payments/blik/accept-a-payment.md#simulate-failures) | #### Débitos bancários | Forma de pagamento | Cenário | Como testar | | ---------------------- | ------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Débito automático SEPA | O cliente paga com débito automático SEPA. | Preencha o formulário usando o número de conta `AT321904300235473204`. Inicialmente, o status do PaymentIntent muda para processando e, três minutos depois, para bem-sucedido. | | Débito automático SEPA | O status da intenção de pagamento do cliente muda de `processing` para `requires_payment_method`. | Preencha o formulário usando o número de conta `AT861904300235473202`. | #### Boletos | Forma de pagamento | Cenário | Como testar | | ------------------ | ------------------------------------------------ | ---------------------------------------------------------------------------------------------- | | Boleto, OXXO | Seu cliente paga com um boleto ou uma guia OXXO. | Selecione boleto ou OXXO como forma de pagamento e envie o pagamento. Feche o diálogo exibido. | Consulte [Testes](https://docs.stripe.com/testing.md) para obter mais informações sobre como testar sua integração. ## Optional: Habilitar formas de pagamento adicionais Navegue para [Gerenciar formas de pagamento para suas contas conectadas](https://dashboard.stripe.com/settings/payment_methods/connected_accounts) no Dashboard para configurar quais formas de pagamento suas contas conectadas aceitam. As alterações nas configurações padrão se aplicam a todas as contas conectadas novas e existentes. Consulte os seguintes recursos para obter informações sobre formas de pagamento: - [Um guia de formas de pagamento](https://stripe.com/payments/payment-methods-guide#choosing-the-right-payment-methods-for-your-business) para ajudar você a escolher as formas de pagamento corretas para sua plataforma. - [Funções da conta](https://docs.stripe.com/connect/account-capabilities.md) para assegurar que as formas de pagamento escolhidas funcionem para suas contas conectadas. - Tabelas de [suporte a formas de pagamento e produtos](https://docs.stripe.com/payments/payment-methods/payment-method-support.md#product-support) para assegurar que suas formas de pagamento escolhidas funcionem para seus produtos da Stripe e fluxos de pagamento. Para cada forma de pagamento, você pode selecionar uma das seguintes opções no menu suspenso: | | | | | **Ativadas por padrão** | Suas contas conectadas aceitam esta forma de pagamento durante o checkout. Algumas formas de pagamento podem ser desativadas ou bloqueadas. Isso ocorre porque suas contas conectadas com *acesso ao Stripe Dashboard* (Platforms can provide connected accounts with access to the full Stripe Dashboard or the Express Dashboard. Otherwise, platforms build an interface for connected accounts using embedded components or the Stripe API) precisam ativá-las em sua página de configurações. | | **Desativadas por padrão** | Suas contas conectadas não aceitam esta forma de pagamento durante o checkout. Se você permitir que contas conectadas com *acessem o Stripe Dashboard* (Platforms can provide connected accounts with access to the full Stripe Dashboard or the Express Dashboard. Otherwise, platforms build an interface for connected accounts using embedded components or the Stripe API) para gerenciar suas próprias formas de pagamento, elas podem ativar esse recurso. | | **Bloqueadas** | Suas contas conectadas não aceitam esta forma de pagamento durante o checkout. Se você permitir que contas conectadas com *acessem o Stripe Dashboard* (Platforms can provide connected accounts with access to the full Stripe Dashboard or the Express Dashboard. Otherwise, platforms build an interface for connected accounts using embedded components or the Stripe API) para gerenciar suas próprias formas de pagamento, elas não têm a opção para ativar esse recurso. | ![Opções 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`. ## Especificar o comerciante da liquidação O comerciante da liquidação depende das [funções](https://docs.stripe.com/connect/account-capabilities.md) da conta e da forma de criação da cobrança. O comerciante da liquidação determina quais dados são usados para fazer a cobrança. Isso inclui a descrição no extrato (da plataforma ou da conta conectada) exibida sobre essa cobrança no extrato bancário ou de cartão de crédito do cliente. A especificação do comerciante da liquidação permite que você defina mais explicitamente para quem as cobranças são criadas. Por exemplo, algumas plataformas preferem ser o comerciante da liquidação porque o cliente final interage diretamente com a plataforma (como plataformas sob demanda). No entanto, algumas plataformas têm contas conectadas que interagem diretamente com os clientes finais (como lojas de uma plataforma de e-commerce). Nesses cenários, pode fazer mais sentido que a conta conectada seja o comerciante da liquidação. Você pode definir o parâmetro `on_behalf_of` para o ID de uma conta conectada para tornar essa conta o comerciante de liquidação do pagamento. Quando usar `on_behalf_of`: - As cobranças são *liquidadas* (When funds are available in your Stripe balance) no país da conta conectada e na *moeda de liquidação* (The settlement currency is the currency your bank account uses). - É usada a estrutura de tarifas do país da conta conectada. - A descrição no extrato da conta conectada é exibida no extrato do cartão de crédito do cliente. - Se a conta conectada estiver em um país diferente do da plataforma, o endereço e o número de telefone da conta conectada serão exibidos no extrato do cartão de crédito do cliente. - O número de dias que um [saldo pendente](https://docs.stripe.com/connect/account-balances.md) é retido antes de receber o repasse depende da configuração [delay_days](https://docs.stripe.com/api/accounts/create.md#create_account-settings-payouts-schedule-delay_days) na conta conectada. > #### API Accounts v2 > > Você não pode usar a API Accounts v2 para gerenciar as configurações de repasse. Use a API Accounts v1. Se `on_behalf_of` for omitido, a plataforma será a empresa registrada para o pagamento. > O parâmetro `on_behalf_of` só é aceito para contas conectadas com uma função de pagamentos, como [card_payments](https://docs.stripe.com/connect/account-capabilities.md#card-payments). As contas sujeitas ao [contrato de serviços de destinatário](https://docs.stripe.com/connect/service-agreement-types.md#recipient) não podem solicitar `card_payments` nem outras funções de pagamento. ```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]"="Restaurant delivery service" \ -d "line_items[0][price_data][unit_amount]"=10000 \ -d "line_items[0][quantity]"=1 \ -d "payment_intent_data[on_behalf_of]"="{{CONNECTEDACCOUNT_ID}}" \ -d "payment_intent_data[transfer_group]"=ORDER100 \ -d mode=payment \ --data-urlencode success_url="https://example.com/success" ``` Incorpore um formulário de pagamento pré-integrado ao seu site usando o [Stripe Checkout](https://docs.stripe.com/payments/checkout.md). Veja como essa integração [se compara a outros tipos 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 cliente] [Lado do servidor] Uma [Checkout Session](https://docs.stripe.com/api/checkout/sessions.md) controla o que o seu cliente vê no formulário de pagamento integrável, como itens de linha, o valor do pedido e a moeda. Crie uma Checkout Session em um endpoint no lado do servidor (por exemplo, `/create-checkout-session`). A resposta inclui um `client_secret` que você usará na próxima etapa para montar o Checkout. ```curl curl https://api.stripe.com/v1/checkout/sessions \ -u "<>:" \ -d "line_items[0][price_data][currency]"=usd \ -d "line_items[0][price_data][product_data][name]"="Restaurant delivery service" \ -d "line_items[0][price_data][unit_amount]"=10000 \ -d "line_items[0][quantity]"=1 \ -d "payment_intent_data[transfer_group]"=ORDER100 \ -d mode=payment \ -d ui_mode=embedded \ --data-urlencode return_url="https://example.com/return?session_id={CHECKOUT_SESSION_ID}" ``` - `line_items` – este atributo representa os itens que o cliente está comprando. Os itens são exibidos no formulário de pagamento integrado. - `payment_intent_data[transfer_group]` – use uma string exclusiva como `transfer_group` para identificar objetos associados entre si. Quando a Stripe cria automaticamente uma cobrança para uma PaymentIntent com um valor de `transfer_group`, atribui o mesmo valor ao `transfer_group` da cobrança. - `return_url` - A Stripe redireciona o cliente para o URL de retorno após ele realizar uma tentativa de pagamento e substitui a string `{CHECKOUT_SESSION_ID}` pelo ID da sessão do Checkout. Use isso para acessar a sessão do Checkout e inspecionar o status para decidir o que mostrar ao cliente. Verifique se o URL de retorno corresponde a uma página no seu site que informa o status do pagamento. Você também pode anexar seus próprios parâmetros de consulta, que permanecem durante o processo de redirecionamento. Consulte [personalizar o comportamento de redirecionamento com um formulário integrado](https://docs.stripe.com/payments/checkout/custom-success-page.md?payment-ui=embedded-form) para obter mais informações. (See full diagram at https://docs.stripe.com/connect/separate-charges-and-transfers) ## 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.initEmbeddedCheckout({ 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. ## Criar uma transferência [Lado do servidor] No seu servidor, envie fundos da sua conta para uma conta conectada criando uma [Transferência](https://docs.stripe.com/api/transfers/create.md) e especificando o `transfer_group` utilizado. ```curl curl https://api.stripe.com/v1/transfers \ -u "<>:" \ -d amount=7000 \ -d currency=usd \ -d destination="{{CONNECTEDACCOUNT_ID}}" \ -d transfer_group=ORDER100 ``` Os valores de transferência e cobrança não precisam ser iguais. Você pode dividir uma única cobrança entre várias transferências ou incluir várias cobranças em uma única transferência. O exemplo a seguir cria uma transferência adicional associada ao mesmo `transfer_group`. ```curl curl https://api.stripe.com/v1/transfers \ -u "<>:" \ -d amount=2000 \ -d currency=usd \ -d destination={{OTHER_CONNECTED_ACCOUNT_ID}} \ -d transfer_group=ORDER100 ``` ### Opções de transferência Você pode atribuir qualquer valor à string `transfer_group`, mas ela deve representar uma única ação de negócios. Também é possível fazer uma transferência sem associar uma cobrança ou `transfer_group`. Por exemplo, quando você paga um provedor, mas não há um pagamento a cliente associado. > O `transfer_group` identifica apenas objetos associados. Ele não afeta nenhuma funcionalidade padrão. Para evitar que uma transferência seja executada antes que os fundos da cobrança associada estejam disponíveis, use o atributo `source_transaction` da transferência. Por padrão, uma solicitação de transferência falha quando o valor excede o [saldo da conta disponível](https://docs.stripe.com/connect/account-balances.md) da plataforma. A Stripe não repete automaticamente solicitações de transferência malsucedidas. Você pode evitar falhas nas solicitações de transferência para transferências associadas a cobranças. Quando você especifica a cobrança associada [como a source_transaction da transferência](https://docs.stripe.com/connect/separate-charges-and-transfers.md#transfer-availability), a solicitação de transferência é bem-sucedida automaticamente. No entanto, não executamos a transferência até que os fundos dessa cobrança estejam disponíveis na conta da plataforma. > Se você usa cobranças e transferências separadas, leve isso em consideração quando planejar seu cronograma de repasses *payout* (A payout is the transfer of funds to an external account, usually a bank account, in the form of a deposit). Repasses automáticos podem interferir nas transferências que não têm uma `source_transaction` definida. ### Formas de pagamento assíncronas Se você estiver usando *formas de pagamento assíncronas* (Asynchronous payment methods can take up to several days to confirm whether the payment has been successful. During this time, the payment can't be guaranteed) (como débito ACH ou débito SEPA), aguarde um evento [charge.succeeded](https://docs.stripe.com/api/events/types.md#event_types-charge.succeeded) antes de criar uma transferência. Ao contrário das cobranças de destino, a Stripe não reverte automaticamente uma transferência se o pagamento assíncrono associado falhar. Se você criar uma transferência e o pagamento falhar posteriormente, o saldo da sua plataforma será debitado pelo valor da transferência. Você deverá então [reverter manualmente a transferência](https://docs.stripe.com/connect/separate-charges-and-transfers.md#reverse-transfers) para recuperar os fundos. ## Teste a integração #### Cartões | Número do cartão | Cenário | Como testar | | ------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------- | | 4242424242424242 | O pagamento com cartão é bem-sucedido e não precisa de autenticação. | Preencha o formulário do cartão de crédito usando o número do cartão de crédito com qualquer validade, CVC e código postal. | | 4000002500003155 | O pagamento com cartão precisa de *autenticação* (Strong Customer Authentication (SCA) is a regulatory requirement in effect as of September 14, 2019, that impacts many European online payments. It requires customers to use two-factor authentication like 3D Secure to verify their purchase). | Preencha o formulário do cartão de crédito usando o número do cartão de crédito com qualquer validade, CVC e código postal. | | 4000000000009995 | O cartão é recusado com um código de recusa como `insufficient_funds`. | Preencha o formulário do cartão de crédito usando o número do cartão de crédito com qualquer validade, CVC e código postal. | | 6205500000000000004 | O cartão UnionPay tem um comprimento variável de 13 a 19 dígitos. | Preencha o formulário do cartão de crédito usando o número do cartão de crédito com qualquer validade, CVC e código postal. | #### Carteiras | Forma de pagamento | Cenário | Como testar | | ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Alipay | O cliente paga com uma forma de pagamento baseada em redirecionamento e [notificação imediata](https://docs.stripe.com/payments/payment-methods.md#payment-notification). | Escolha qualquer forma de pagamento baseada em redirecionamento, preencha os dados obrigatórios e confirme o pagamento. Em seguida, clique em **Concluir o pagamento de teste** na página de redirecionamento. | #### Débito bancário autenticado | Forma de pagamento | Cenário | Como testar | | ------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Débito automático BECS | O cliente paga com débito automático BECS. | Preencha o formulário usando o número de conta `900123456` e BSB `000000`. Inicialmente, o status do PaymentIntent muda para `processing` e, 3 minutos depois, para `succeeded`. | | Débito automático BECS | O pagamento do cliente falha com um código de erro `account_closed`. | Preencha o formulário usando o número da conta `111111113` e BSB `000000`. | | Bancontact, EPS, iDEAL, e Przelewy24 | Seu cliente não faz a autenticação na página de redirecionamento de uma forma de pagamento baseada em redirecionamento e notificação imediata. | Escolha qualquer forma de pagamento baseada em redirecionamento, preencha os dados obrigatórios e confirme o pagamento. Em seguida, clique em **Falhar pagamento de teste** na página de redirecionamento. | | Pay by Bank | O cliente paga com uma forma de pagamento baseada em redirecionamento e [notificação posterior](https://docs.stripe.com/payments/payment-methods.md#payment-notification). | Escolha a forma de pagamento, preencha os dados obrigatórios e confirme o pagamento. Em seguida, clique em **Concluir o pagamento de teste** na página de redirecionamento. | | Pay by Bank | Seu cliente não faz a autenticação na página de redirecionamento de uma forma de pagamento baseada em redirecionamento e notificação posterior. | Escolha a forma de pagamento, preencha os dados obrigatórios e confirme o pagamento. Em seguida, clique em **Falhar o pagamento de teste** na página de redirecionamento. | | BLIK | Os pagamentos BLIK falham de várias formas: falhas imediatas (por exemplo, o código está vencido ou inválido), erros atrasados (o banco recusa) ou limites de tempo (o cliente não respondeu a tempo). | Use padrões de e-mail para [simular as diferentes falhas.](https://docs.stripe.com/payments/blik/accept-a-payment.md#simulate-failures) | #### Débitos bancários | Forma de pagamento | Cenário | Como testar | | ---------------------- | ------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Débito automático SEPA | O cliente paga com débito automático SEPA. | Preencha o formulário usando o número de conta `AT321904300235473204`. Inicialmente, o status do PaymentIntent muda para processando e, três minutos depois, para bem-sucedido. | | Débito automático SEPA | O status da intenção de pagamento do cliente muda de `processing` para `requires_payment_method`. | Preencha o formulário usando o número de conta `AT861904300235473202`. | #### Boletos | Forma de pagamento | Cenário | Como testar | | ------------------ | ------------------------------------------------ | ---------------------------------------------------------------------------------------------- | | Boleto, OXXO | Seu cliente paga com um boleto ou uma guia OXXO. | Selecione boleto ou OXXO como forma de pagamento e envie o pagamento. Feche o diálogo exibido. | Consulte [Testes](https://docs.stripe.com/testing.md) para obter mais informações sobre como testar sua integração. ## Optional: Habilitar formas de pagamento adicionais Navegue para [Gerenciar formas de pagamento para suas contas conectadas](https://dashboard.stripe.com/settings/payment_methods/connected_accounts) no Dashboard para configurar quais formas de pagamento suas contas conectadas aceitam. As alterações nas configurações padrão se aplicam a todas as contas conectadas novas e existentes. Consulte os seguintes recursos para obter informações sobre formas de pagamento: - [Um guia de formas de pagamento](https://stripe.com/payments/payment-methods-guide#choosing-the-right-payment-methods-for-your-business) para ajudar você a escolher as formas de pagamento corretas para sua plataforma. - [Funções da conta](https://docs.stripe.com/connect/account-capabilities.md) para assegurar que as formas de pagamento escolhidas funcionem para suas contas conectadas. - Tabelas de [suporte a formas de pagamento e produtos](https://docs.stripe.com/payments/payment-methods/payment-method-support.md#product-support) para assegurar que suas formas de pagamento escolhidas funcionem para seus produtos da Stripe e fluxos de pagamento. Para cada forma de pagamento, você pode selecionar uma das seguintes opções no menu suspenso: | | | | | **Ativadas por padrão** | Suas contas conectadas aceitam esta forma de pagamento durante o checkout. Algumas formas de pagamento podem ser desativadas ou bloqueadas. Isso ocorre porque suas contas conectadas com *acesso ao Stripe Dashboard* (Platforms can provide connected accounts with access to the full Stripe Dashboard or the Express Dashboard. Otherwise, platforms build an interface for connected accounts using embedded components or the Stripe API) precisam ativá-las em sua página de configurações. | | **Desativadas por padrão** | Suas contas conectadas não aceitam esta forma de pagamento durante o checkout. Se você permitir que contas conectadas com *acessem o Stripe Dashboard* (Platforms can provide connected accounts with access to the full Stripe Dashboard or the Express Dashboard. Otherwise, platforms build an interface for connected accounts using embedded components or the Stripe API) para gerenciar suas próprias formas de pagamento, elas podem ativar esse recurso. | | **Bloqueadas** | Suas contas conectadas não aceitam esta forma de pagamento durante o checkout. Se você permitir que contas conectadas com *acessem o Stripe Dashboard* (Platforms can provide connected accounts with access to the full Stripe Dashboard or the Express Dashboard. Otherwise, platforms build an interface for connected accounts using embedded components or the Stripe API) para gerenciar suas próprias formas de pagamento, elas não têm a opção para ativar esse recurso. | ![Opções 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`. ## Especificar o comerciante da liquidação O comerciante da liquidação depende das [funções](https://docs.stripe.com/connect/account-capabilities.md) da conta e da forma de criação da cobrança. O comerciante da liquidação determina quais dados são usados para fazer a cobrança. Isso inclui a descrição no extrato (da plataforma ou da conta conectada) exibida sobre essa cobrança no extrato bancário ou de cartão de crédito do cliente. A especificação do comerciante da liquidação permite que você defina mais explicitamente para quem as cobranças são criadas. Por exemplo, algumas plataformas preferem ser o comerciante da liquidação porque o cliente final interage diretamente com a plataforma (como plataformas sob demanda). No entanto, algumas plataformas têm contas conectadas que interagem diretamente com os clientes finais (como lojas de uma plataforma de e-commerce). Nesses cenários, pode fazer mais sentido que a conta conectada seja o comerciante da liquidação. Você pode definir o parâmetro `on_behalf_of` para o ID de uma conta conectada para tornar essa conta o comerciante de liquidação do pagamento. Quando usar `on_behalf_of`: - As cobranças são *liquidadas* (When funds are available in your Stripe balance) no país da conta conectada e na *moeda de liquidação* (The settlement currency is the currency your bank account uses). - É usada a estrutura de tarifas do país da conta conectada. - A descrição no extrato da conta conectada é exibida no extrato do cartão de crédito do cliente. - Se a conta conectada estiver em um país diferente do da plataforma, o endereço e o número de telefone da conta conectada serão exibidos no extrato do cartão de crédito do cliente. - O número de dias que um [saldo pendente](https://docs.stripe.com/connect/account-balances.md) é retido antes de receber o repasse depende da configuração [delay_days](https://docs.stripe.com/api/accounts/create.md#create_account-settings-payouts-schedule-delay_days) na conta conectada. > #### API Accounts v2 > > Você não pode usar a API Accounts v2 para gerenciar as configurações de repasse. Use a API Accounts v1. Se `on_behalf_of` for omitido, a plataforma será a empresa registrada para o pagamento. > O parâmetro `on_behalf_of` só é aceito para contas conectadas com uma função de pagamentos, como [card_payments](https://docs.stripe.com/connect/account-capabilities.md#card-payments). As contas sujeitas ao [contrato de serviços de destinatário](https://docs.stripe.com/connect/service-agreement-types.md#recipient) não podem solicitar `card_payments` nem outras funções de pagamento. ```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]"="Restaurant delivery service" \ -d "line_items[0][price_data][unit_amount]"=10000 \ -d "line_items[0][quantity]"=1 \ -d "payment_intent_data[on_behalf_of]"="{{CONNECTEDACCOUNT_ID}}" \ -d "payment_intent_data[transfer_group]"=ORDER100 \ -d mode=payment \ -d ui_mode=embedded \ --data-urlencode return_url="https://example.com/return" ``` Crie uma integração de pagamentos personalizada incorporando componentes de IU ao seu site com [Stripe Elements](https://docs.stripe.com/payments/elements.md). O código no lado do cliente e no lado do servidor cria um formulário de checkout que aceita várias formas de pagamento. Veja como essa integração [se compara a outros tipos 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 em 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/separate-charges-and-transfers) As formas de pagamento mostradas aos clientes durante o processo de checkout também estão incluídas no PaymentIntent. Você pode permitir que a Stripe extraia automaticamente as formas de pagamento das suas configurações de 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 a moeda, as restrições e outros parâmetros dessas formas de pagamento para criar a lista das que são 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, uma moeda e um valor de `transfer_group` para associar posteriormente à transferência de fundos. 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 gerencia 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=10000 \ -d currency=usd \ -d "automatic_payment_methods[enabled]"=true \ -d transfer_group=ORDER100 ``` #### Listar manualmente as formas de pagamento Crie uma PaymentIntent no seu servidor com um valor, moeda, uma lista de tipos de forma de pagamento e um valor `transfer_group` para associar posteriormente à transferência de fundos. Sempre decida quanto deseja cobrar no lado do servidor, um ambiente confiável, e não no lado do cliente. Isso evita que clientes mal-intencionados escolham os próprios preços. ```curl curl https://api.stripe.com/v1/payment_intents \ -u "<>:" \ -d amount=10000 \ -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 transfer_group=ORDER100 ``` 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 [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. | ## Criar uma transferência [Lado do servidor] No seu servidor, envie fundos da sua conta para uma conta conectada criando uma [Transferência](https://docs.stripe.com/api/transfers/create.md) e especificando o `transfer_group` utilizado. ```curl curl https://api.stripe.com/v1/transfers \ -u "<>:" \ -d amount=7000 \ -d currency=usd \ -d destination="{{CONNECTEDACCOUNT_ID}}" \ -d transfer_group=ORDER100 ``` Os valores de transferência e cobrança não precisam ser iguais. Você pode dividir uma única cobrança entre várias transferências ou incluir várias cobranças em uma única transferência. O exemplo a seguir cria uma transferência adicional associada ao mesmo `transfer_group`. ```curl curl https://api.stripe.com/v1/transfers \ -u "<>:" \ -d amount=2000 \ -d currency=usd \ -d destination={{OTHER_CONNECTED_ACCOUNT_ID}} \ -d transfer_group=ORDER100 ``` ### Opções de transferência Você pode atribuir qualquer valor à string `transfer_group`, mas ela deve representar uma única ação de negócios. Também é possível fazer uma transferência sem associar uma cobrança ou `transfer_group`. Por exemplo, quando você paga um provedor, mas não há um pagamento a cliente associado. > O `transfer_group` identifica apenas objetos associados. Ele não afeta nenhuma funcionalidade padrão. Para evitar que uma transferência seja executada antes que os fundos da cobrança associada estejam disponíveis, use o atributo `source_transaction` da transferência. Por padrão, uma solicitação de transferência falha quando o valor excede o [saldo da conta disponível](https://docs.stripe.com/connect/account-balances.md) da plataforma. A Stripe não repete automaticamente solicitações de transferência malsucedidas. Você pode evitar falhas nas solicitações de transferência para transferências associadas a cobranças. Quando você especifica a cobrança associada [como a source_transaction da transferência](https://docs.stripe.com/connect/separate-charges-and-transfers.md#transfer-availability), a solicitação de transferência é bem-sucedida automaticamente. No entanto, não executamos a transferência até que os fundos dessa cobrança estejam disponíveis na conta da plataforma. > Se você usa cobranças e transferências separadas, leve isso em consideração quando planejar seu cronograma de repasses *payout* (A payout is the transfer of funds to an external account, usually a bank account, in the form of a deposit). Repasses automáticos podem interferir nas transferências que não têm uma `source_transaction` definida. ### Formas de pagamento assíncronas Se você estiver usando *formas de pagamento assíncronas* (Asynchronous payment methods can take up to several days to confirm whether the payment has been successful. During this time, the payment can't be guaranteed) (como débito ACH ou débito SEPA), aguarde um evento [charge.succeeded](https://docs.stripe.com/api/events/types.md#event_types-charge.succeeded) antes de criar uma transferência. Ao contrário das cobranças de destino, a Stripe não reverte automaticamente uma transferência se o pagamento assíncrono associado falhar. Se você criar uma transferência e o pagamento falhar posteriormente, o saldo da sua plataforma será debitado pelo valor da transferência. Você deverá então [reverter manualmente a transferência](https://docs.stripe.com/connect/separate-charges-and-transfers.md#reverse-transfers) para recuperar os fundos. ## Teste a integração #### Cartões | Número do cartão | Cenário | Como testar | | ------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------- | | 4242424242424242 | O pagamento com cartão é bem-sucedido e não precisa de autenticação. | Preencha o formulário do cartão de crédito usando o número do cartão de crédito com qualquer validade, CVC e código postal. | | 4000002500003155 | O pagamento com cartão precisa de *autenticação* (Strong Customer Authentication (SCA) is a regulatory requirement in effect as of September 14, 2019, that impacts many European online payments. It requires customers to use two-factor authentication like 3D Secure to verify their purchase). | Preencha o formulário do cartão de crédito usando o número do cartão de crédito com qualquer validade, CVC e código postal. | | 4000000000009995 | O cartão é recusado com um código de recusa como `insufficient_funds`. | Preencha o formulário do cartão de crédito usando o número do cartão de crédito com qualquer validade, CVC e código postal. | | 6205500000000000004 | O cartão UnionPay tem um comprimento variável de 13 a 19 dígitos. | Preencha o formulário do cartão de crédito usando o número do cartão de crédito com qualquer validade, CVC e código postal. | #### Carteiras | Forma de pagamento | Cenário | Como testar | | ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Alipay | O cliente paga com uma forma de pagamento baseada em redirecionamento e [notificação imediata](https://docs.stripe.com/payments/payment-methods.md#payment-notification). | Escolha qualquer forma de pagamento baseada em redirecionamento, preencha os dados obrigatórios e confirme o pagamento. Em seguida, clique em **Concluir o pagamento de teste** na página de redirecionamento. | #### Débito bancário autenticado | Forma de pagamento | Cenário | Como testar | | ------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Débito automático BECS | O cliente paga com débito automático BECS. | Preencha o formulário usando o número de conta `900123456` e BSB `000000`. Inicialmente, o status do PaymentIntent muda para `processing` e, 3 minutos depois, para `succeeded`. | | Débito automático BECS | O pagamento do cliente falha com um código de erro `account_closed`. | Preencha o formulário usando o número da conta `111111113` e BSB `000000`. | | Bancontact, EPS, iDEAL, e Przelewy24 | Seu cliente não faz a autenticação na página de redirecionamento de uma forma de pagamento baseada em redirecionamento e notificação imediata. | Escolha qualquer forma de pagamento baseada em redirecionamento, preencha os dados obrigatórios e confirme o pagamento. Em seguida, clique em **Falhar pagamento de teste** na página de redirecionamento. | | Pay by Bank | O cliente paga com uma forma de pagamento baseada em redirecionamento e [notificação posterior](https://docs.stripe.com/payments/payment-methods.md#payment-notification). | Escolha a forma de pagamento, preencha os dados obrigatórios e confirme o pagamento. Em seguida, clique em **Concluir o pagamento de teste** na página de redirecionamento. | | Pay by Bank | Seu cliente não faz a autenticação na página de redirecionamento de uma forma de pagamento baseada em redirecionamento e notificação posterior. | Escolha a forma de pagamento, preencha os dados obrigatórios e confirme o pagamento. Em seguida, clique em **Falhar o pagamento de teste** na página de redirecionamento. | | BLIK | Os pagamentos BLIK falham de várias formas: falhas imediatas (por exemplo, o código está vencido ou inválido), erros atrasados (o banco recusa) ou limites de tempo (o cliente não respondeu a tempo). | Use padrões de e-mail para [simular as diferentes falhas.](https://docs.stripe.com/payments/blik/accept-a-payment.md#simulate-failures) | #### Débitos bancários | Forma de pagamento | Cenário | Como testar | | ---------------------- | ------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Débito automático SEPA | O cliente paga com débito automático SEPA. | Preencha o formulário usando o número de conta `AT321904300235473204`. Inicialmente, o status do PaymentIntent muda para processando e, três minutos depois, para bem-sucedido. | | Débito automático SEPA | O status da intenção de pagamento do cliente muda de `processing` para `requires_payment_method`. | Preencha o formulário usando o número de conta `AT861904300235473202`. | #### Boletos | Forma de pagamento | Cenário | Como testar | | ------------------ | ------------------------------------------------ | ---------------------------------------------------------------------------------------------- | | Boleto, OXXO | Seu cliente paga com um boleto ou uma guia OXXO. | Selecione boleto ou OXXO como forma de pagamento e envie o pagamento. Feche o diálogo exibido. | Consulte [Testes](https://docs.stripe.com/testing.md) para obter mais informações sobre como testar sua integração. ## Optional: Habilitar formas de pagamento adicionais Navegue para [Gerenciar formas de pagamento para suas contas conectadas](https://dashboard.stripe.com/settings/payment_methods/connected_accounts) no Dashboard para configurar quais formas de pagamento suas contas conectadas aceitam. As alterações nas configurações padrão se aplicam a todas as contas conectadas novas e existentes. Consulte os seguintes recursos para obter informações sobre formas de pagamento: - [Um guia de formas de pagamento](https://stripe.com/payments/payment-methods-guide#choosing-the-right-payment-methods-for-your-business) para ajudar você a escolher as formas de pagamento corretas para sua plataforma. - [Funções da conta](https://docs.stripe.com/connect/account-capabilities.md) para assegurar que as formas de pagamento escolhidas funcionem para suas contas conectadas. - Tabelas de [suporte a formas de pagamento e produtos](https://docs.stripe.com/payments/payment-methods/payment-method-support.md#product-support) para assegurar que suas formas de pagamento escolhidas funcionem para seus produtos da Stripe e fluxos de pagamento. Para cada forma de pagamento, você pode selecionar uma das seguintes opções no menu suspenso: | | | | | **Ativadas por padrão** | Suas contas conectadas aceitam esta forma de pagamento durante o checkout. Algumas formas de pagamento podem ser desativadas ou bloqueadas. Isso ocorre porque suas contas conectadas com *acesso ao Stripe Dashboard* (Platforms can provide connected accounts with access to the full Stripe Dashboard or the Express Dashboard. Otherwise, platforms build an interface for connected accounts using embedded components or the Stripe API) precisam ativá-las em sua página de configurações. | | **Desativadas por padrão** | Suas contas conectadas não aceitam esta forma de pagamento durante o checkout. Se você permitir que contas conectadas com *acessem o Stripe Dashboard* (Platforms can provide connected accounts with access to the full Stripe Dashboard or the Express Dashboard. Otherwise, platforms build an interface for connected accounts using embedded components or the Stripe API) para gerenciar suas próprias formas de pagamento, elas podem ativar esse recurso. | | **Bloqueadas** | Suas contas conectadas não aceitam esta forma de pagamento durante o checkout. Se você permitir que contas conectadas com *acessem o Stripe Dashboard* (Platforms can provide connected accounts with access to the full Stripe Dashboard or the Express Dashboard. Otherwise, platforms build an interface for connected accounts using embedded components or the Stripe API) para gerenciar suas próprias formas de pagamento, elas não têm a opção para ativar esse recurso. | ![Opções 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`. ## Especificar o comerciante da liquidação O comerciante da liquidação depende das [funções](https://docs.stripe.com/connect/account-capabilities.md) da conta e da forma de criação da cobrança. O comerciante da liquidação determina quais dados são usados para fazer a cobrança. Isso inclui a descrição no extrato (da plataforma ou da conta conectada) exibida sobre essa cobrança no extrato bancário ou de cartão de crédito do cliente. A especificação do comerciante da liquidação permite que você defina mais explicitamente para quem as cobranças são criadas. Por exemplo, algumas plataformas preferem ser o comerciante da liquidação porque o cliente final interage diretamente com a plataforma (como plataformas sob demanda). No entanto, algumas plataformas têm contas conectadas que interagem diretamente com os clientes finais (como lojas de uma plataforma de e-commerce). Nesses cenários, pode fazer mais sentido que a conta conectada seja o comerciante da liquidação. Você pode definir o parâmetro `on_behalf_of` para o ID de uma conta conectada para tornar essa conta o comerciante de liquidação do pagamento. Quando usar `on_behalf_of`: - As cobranças são *liquidadas* (When funds are available in your Stripe balance) no país da conta conectada e na *moeda de liquidação* (The settlement currency is the currency your bank account uses). - É usada a estrutura de tarifas do país da conta conectada. - A descrição no extrato da conta conectada é exibida no extrato do cartão de crédito do cliente. - Se a conta conectada estiver em um país diferente do da plataforma, o endereço e o número de telefone da conta conectada serão exibidos no extrato do cartão de crédito do cliente. - O número de dias que um [saldo pendente](https://docs.stripe.com/connect/account-balances.md) é retido antes de receber o repasse depende da configuração [delay_days](https://docs.stripe.com/api/accounts/create.md#create_account-settings-payouts-schedule-delay_days) na conta conectada. > #### API Accounts v2 > > Você não pode usar a API Accounts v2 para gerenciar as configurações de repasse. Use a API Accounts v1. Se `on_behalf_of` for omitido, a plataforma será a empresa registrada para o pagamento. > O parâmetro `on_behalf_of` só é aceito para contas conectadas com uma função de pagamentos, como [card_payments](https://docs.stripe.com/connect/account-capabilities.md#card-payments). As contas sujeitas ao [contrato de serviços de destinatário](https://docs.stripe.com/connect/service-agreement-types.md#recipient) não podem solicitar `card_payments` nem outras funções de pagamento. ```curl curl https://api.stripe.com/v1/payment_intents \ -u "<>:" \ -d amount=10000 \ -d currency=usd \ -d "automatic_payment_methods[enabled]"=true \ -d on_behalf_of="{{CONNECTEDACCOUNT_ID}}" \ -d transfer_group=ORDER100 ``` ![](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 servidor se comuniquem com a API da Stripe. Use nossas bibliotecas oficiais para acessar a API da Stripe a partir do 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. ## Adicione um endpoint [Lado do servidor] Esta integração usa três objetos da API da Stripe: 1. Um [PaymentIntent](https://docs.stripe.com/api/payment_intents.md). A Stripe usa isso para representar sua intenção de coletar um pagamento de um cliente, acompanhando suas tentativas de cobrança e alterações de estado do pagamento durante todo o processo. 1. Um *cliente* (Customer objects represent customers of your business. They let you reuse payment methods and give you the ability to track multiple payments) (opcional). Para configurar uma forma de pagamento para pagamentos futuros, ela precisa estar vinculada a um cliente. Crie um objeto Customer quando o cliente abrir uma conta na sua empresa. Se o cliente pagar como convidado, você pode criar o objeto Customer antes do pagamento e associá-lo à sua representação interna da conta do cliente, mais tarde. 1. Uma chave efêmera de cliente (opcional). Os dados do objeto Customer são confidenciais e não podem ser recuperados diretamente do aplicativo. Uma chave efêmera concede ao SDK acesso temporário ao cliente. Se você quiser salvar cartões e permitir que clientes recorrentes reutilizem cartões salvos, você precisa dos objetos Customer e Customer Ephemeral Key para sua integração. Caso contrário, você poderá omitir esses objetos. Por motivos de segurança, seu aplicativo não pode criar esses objetos. Em vez disso, adicione um endpoint ao servidor que: 1. Recuperar ou criar um Customer. 1. Criar uma chave efêmera para o Customer. 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), o [cliente](https://docs.stripe.com/api/payment_intents/create.md#create_payment_intent-customer) e um [grupo de transferência](https://docs.stripe.com/api/payment_intents/create.md#create_payment_intent-transfer_group) para associar posteriormente à transferência de fundos. 1. Retorna o *segredo do cliente* (The client secret is a unique key returned from Stripe as part of a PaymentIntent. This key lets the client access important fields from the PaymentIntent (status, amount, currency) while hiding sensitive ones (metadata, customer)) do Payment Intent, o `secret` da chave efêmera, o [ID do cliente](https://docs.stripe.com/api/customers/object.md#customer_object-id) e sua [chave publicável](https://dashboard.stripe.com/apikeys) ao aplicativo. As formas de pagamento mostradas aos clientes durante o processo de checkout também estão incluídas no PaymentIntent. Você pode permitir que a Stripe obtenha as formas de pagamento das [configurações do Dashboard](https://dashboard.stripe.com/settings/payment_methods) ou pode 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 a moeda, as restrições e outros parâmetros dessas formas de pagamento para criar a lista das que são 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. Ocultamos as formas de pagamento de menor prioridade em um menu de navegação. #### Gerenciar formas de pagamento no Dashboard Você pode clonar e executar uma implementação de exemplo deste endpoint diretamente no [CodeSandbox](https://codesandbox.io/p/devbox/suspicious-lalande-l325w6) para testar o comportamento. #### 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" # Create an Ephemeral Key for the Customer curl https://api.stripe.com/v1/ephemeral_keys \ -u <>: \ -H "Stripe-Version: 2026-02-25.clover" \ -X "POST" \ -d "customer"="{{CUSTOMER_ID}}" \ # Create a PaymentIntent curl https://api.stripe.com/v1/payment_intents \ -u <>: \ -X "POST" \ -d "customer"="{{CUSTOMER_ID}}" \ -d "amount"=10000 \ -d "currency"="usd" \ # In the latest version of the API, specifying the `automatic_payment_methods` parameter # is optional because Stripe enables its functionality by default. -d "automatic_payment_methods[enabled]"=true \ -d transfer_group="ORDER100" \ ``` #### Listar manualmente as formas de pagamento Você pode clonar e executar uma implementação de exemplo deste endpoint diretamente no [CodeSandbox](https://codesandbox.io/p/devbox/suspicious-lalande-l325w6) para testar o comportamento. #### 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" # Create an Ephemeral Key for the Customer curl https://api.stripe.com/v1/ephemeral_keys \ -u <>: \ -H "Stripe-Version: 2026-02-25.clover" \ -X "POST" \ -d "customer"="{{CUSTOMER_ID}}" \ # Create a PaymentIntent curl https://api.stripe.com/v1/payment_intents \ -u <>: \ -X "POST" \ -d "customer"="{{CUSTOMER_ID}}" \ -d "amount"=10000 \ -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 transfer_group="ORDER100" \ ``` 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 saber 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. | ## Criar uma transferência [Lado do servidor] No seu servidor, envie fundos da sua conta para uma conta conectada criando uma [Transferência](https://docs.stripe.com/api/transfers/create.md) e especificando o `transfer_group` utilizado. ```curl curl https://api.stripe.com/v1/transfers \ -u "<>:" \ -d amount=7000 \ -d currency=usd \ -d destination="{{CONNECTEDACCOUNT_ID}}" \ -d transfer_group=ORDER100 ``` Os valores de transferência e cobrança não precisam ser iguais. Você pode dividir uma única cobrança entre várias transferências ou incluir várias cobranças em uma única transferência. O exemplo a seguir cria uma transferência adicional associada ao mesmo `transfer_group`. ```curl curl https://api.stripe.com/v1/transfers \ -u "<>:" \ -d amount=2000 \ -d currency=usd \ -d destination={{OTHER_CONNECTED_ACCOUNT_ID}} \ -d transfer_group=ORDER100 ``` ### Opções de transferência Você pode atribuir qualquer valor à string `transfer_group`, mas ela deve representar uma única ação de negócios. Também é possível fazer uma transferência sem associar uma cobrança ou `transfer_group`. Por exemplo, quando você paga um provedor, mas não há um pagamento a cliente associado. > O `transfer_group` identifica apenas objetos associados. Ele não afeta nenhuma funcionalidade padrão. Para evitar que uma transferência seja executada antes que os fundos da cobrança associada estejam disponíveis, use o atributo `source_transaction` da transferência. Por padrão, uma solicitação de transferência falha quando o valor excede o [saldo da conta disponível](https://docs.stripe.com/connect/account-balances.md) da plataforma. A Stripe não repete automaticamente solicitações de transferência malsucedidas. Você pode evitar falhas nas solicitações de transferência para transferências associadas a cobranças. Quando você especifica a cobrança associada [como a source_transaction da transferência](https://docs.stripe.com/connect/separate-charges-and-transfers.md#transfer-availability), a solicitação de transferência é bem-sucedida automaticamente. No entanto, não executamos a transferência até que os fundos dessa cobrança estejam disponíveis na conta da plataforma. > Se você usa cobranças e transferências separadas, leve isso em consideração quando planejar seu cronograma de repasses *payout* (A payout is the transfer of funds to an external account, usually a bank account, in the form of a deposit). Repasses automáticos podem interferir nas transferências que não têm uma `source_transaction` definida. ### Formas de pagamento assíncronas Se você estiver usando *formas de pagamento assíncronas* (Asynchronous payment methods can take up to several days to confirm whether the payment has been successful. During this time, the payment can't be guaranteed) (como débito ACH ou débito SEPA), aguarde um evento [charge.succeeded](https://docs.stripe.com/api/events/types.md#event_types-charge.succeeded) antes de criar uma transferência. Ao contrário das cobranças de destino, a Stripe não reverte automaticamente uma transferência se o pagamento assíncrono associado falhar. Se você criar uma transferência e o pagamento falhar posteriormente, o saldo da sua plataforma será debitado pelo valor da transferência. Você deverá então [reverter manualmente a transferência](https://docs.stripe.com/connect/separate-charges-and-transfers.md#reverse-transfers) para recuperar os fundos. ## Teste 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 de Apple Pay](https://docs.stripe.com/apple-pay.md#present-payment-sheet) e use `ApplePayContext` para coletar pagamento com o 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 Customize colors, fonts, and so on to match the look and feel of your app by using the [appearance API](https://docs.stripe.com/elements/appearance-api/mobile.md?platform=ios). ### Layout da forma de pagamento Configure o layout das formas de pagamento na planilha usando [paymentMethodLayout](https://stripe.dev/stripe-ios/stripepaymentsheet/documentation/stripepaymentsheet/paymentsheet/configuration-swift.struct/paymentmethodlayout). Você pode exibi-los horizontalmente, verticalmente ou deixar a Stripe otimizar o layout automaticamente. ![](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: Habilitar formas de pagamento adicionais Navegue para [Gerenciar formas de pagamento para suas contas conectadas](https://dashboard.stripe.com/settings/payment_methods/connected_accounts) no Dashboard para configurar quais formas de pagamento suas contas conectadas aceitam. As alterações nas configurações padrão se aplicam a todas as contas conectadas novas e existentes. Consulte os seguintes recursos para obter informações sobre formas de pagamento: - [Um guia de formas de pagamento](https://stripe.com/payments/payment-methods-guide#choosing-the-right-payment-methods-for-your-business) para ajudar você a escolher as formas de pagamento corretas para sua plataforma. - [Funções da conta](https://docs.stripe.com/connect/account-capabilities.md) para assegurar que as formas de pagamento escolhidas funcionem para suas contas conectadas. - Tabelas de [suporte a formas de pagamento e produtos](https://docs.stripe.com/payments/payment-methods/payment-method-support.md#product-support) para assegurar que suas formas de pagamento escolhidas funcionem para seus produtos da Stripe e fluxos de pagamento. Para cada forma de pagamento, você pode selecionar uma das seguintes opções no menu suspenso: | | | | | **Ativadas por padrão** | Suas contas conectadas aceitam esta forma de pagamento durante o checkout. Algumas formas de pagamento podem ser desativadas ou bloqueadas. Isso ocorre porque suas contas conectadas com *acesso ao Stripe Dashboard* (Platforms can provide connected accounts with access to the full Stripe Dashboard or the Express Dashboard. Otherwise, platforms build an interface for connected accounts using embedded components or the Stripe API) precisam ativá-las em sua página de configurações. | | **Desativadas por padrão** | Suas contas conectadas não aceitam esta forma de pagamento durante o checkout. Se você permitir que contas conectadas com *acessem o Stripe Dashboard* (Platforms can provide connected accounts with access to the full Stripe Dashboard or the Express Dashboard. Otherwise, platforms build an interface for connected accounts using embedded components or the Stripe API) para gerenciar suas próprias formas de pagamento, elas podem ativar esse recurso. | | **Bloqueadas** | Suas contas conectadas não aceitam esta forma de pagamento durante o checkout. Se você permitir que contas conectadas com *acessem o Stripe Dashboard* (Platforms can provide connected accounts with access to the full Stripe Dashboard or the Express Dashboard. Otherwise, platforms build an interface for connected accounts using embedded components or the Stripe API) para gerenciar suas próprias formas de pagamento, elas não têm a opção para ativar esse recurso. | ![Opções 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`. ## Especificar o comerciante da liquidação O comerciante da liquidação depende das [funções](https://docs.stripe.com/connect/account-capabilities.md) da conta e da forma de criação da cobrança. O comerciante da liquidação determina quais dados são usados para fazer a cobrança. Isso inclui a descrição no extrato (da plataforma ou da conta conectada) exibida sobre essa cobrança no extrato bancário ou de cartão de crédito do cliente. A especificação do comerciante da liquidação permite que você defina mais explicitamente para quem as cobranças são criadas. Por exemplo, algumas plataformas preferem ser o comerciante da liquidação porque o cliente final interage diretamente com a plataforma (como plataformas sob demanda). No entanto, algumas plataformas têm contas conectadas que interagem diretamente com os clientes finais (como lojas de uma plataforma de e-commerce). Nesses cenários, pode fazer mais sentido que a conta conectada seja o comerciante da liquidação. Você pode definir o parâmetro `on_behalf_of` para o ID de uma conta conectada para tornar essa conta o comerciante de liquidação do pagamento. Quando usar `on_behalf_of`: - As cobranças são *liquidadas* (When funds are available in your Stripe balance) no país da conta conectada e na *moeda de liquidação* (The settlement currency is the currency your bank account uses). - É usada a estrutura de tarifas do país da conta conectada. - A descrição no extrato da conta conectada é exibida no extrato do cartão de crédito do cliente. - Se a conta conectada estiver em um país diferente do da plataforma, o endereço e o número de telefone da conta conectada serão exibidos no extrato do cartão de crédito do cliente. - O número de dias que um [saldo pendente](https://docs.stripe.com/connect/account-balances.md) é retido antes de receber o repasse depende da configuração [delay_days](https://docs.stripe.com/api/accounts/create.md#create_account-settings-payouts-schedule-delay_days) na conta conectada. > #### API Accounts v2 > > Você não pode usar a API Accounts v2 para gerenciar as configurações de repasse. Use a API Accounts v1. Se `on_behalf_of` for omitido, a plataforma será a empresa registrada para o pagamento. > O parâmetro `on_behalf_of` só é aceito para contas conectadas com uma função de pagamentos, como [card_payments](https://docs.stripe.com/connect/account-capabilities.md#card-payments). As contas sujeitas ao [contrato de serviços de destinatário](https://docs.stripe.com/connect/service-agreement-types.md#recipient) não podem solicitar `card_payments` nem outras funções de pagamento. ```curl curl https://api.stripe.com/v1/payment_intents \ -u "<>:" \ -d amount=10000 \ -d currency=usd \ -d "automatic_payment_methods[enabled]"=true \ -d on_behalf_of="{{CONNECTEDACCOUNT_ID}}" \ -d transfer_group=ORDER100 ``` ![](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 servidor se comuniquem com a API da Stripe. Use as bibliotecas oficiais para acessar a API da Stripe partir do seu servidor: #### Ruby ```bash # Available as a gem sudo gem install stripe ``` ```ruby # If you use bundler, you can add this line to your Gemfile gem 'stripe' ``` ### Lado do cliente O [SDK da Stripe para Android](https://github.com/stripe/stripe-android) é de código aberto e [totalmente documentado](https://stripe.dev/stripe-android/). Para instalar o SDK, adicione `stripe-android` ao bloco `dependencies` do arquivo [app/build.gradle](https://developer.android.com/studio/build/dependencies): #### Kotlin ```kotlin plugins { id("com.android.application") } android { ... } dependencies { // ... // Stripe Android SDK implementation("com.stripe:stripe-android:23.0.2") // Include the financial connections SDK to support US bank account as a payment method implementation("com.stripe:financial-connections:23.0.2") } ``` > Veja mais informações sobre o último lançamento de SDK e as versões anteriores na página [Lançamentos](https://github.com/stripe/stripe-android/releases) no GitHub. Para receber notificações quando um novo lançamento for publicado, [assista aos lançamentos do repositório](https://docs.github.com/en/github/managing-subscriptions-and-notifications-on-github/configuring-notifications#configuring-your-watch-settings-for-an-individual-repository). Configure o SDK com sua [chave publicável](https://dashboard.stripe.com/apikeys) da Stripe, de modo que seja possível fazer solicitações à API Stripe, como em sua subcategoria `Application`: #### Kotlin ```kotlin import com.stripe.android.PaymentConfiguration class MyApp : Application() { override fun onCreate() { super.onCreate() PaymentConfiguration.init( applicationContext, "<>" ) } } ``` > Use suas [chaves de teste](https://docs.stripe.com/keys.md#obtain-api-keys) enquanto testa e desenvolve, e suas chaves de [modo de produção](https://docs.stripe.com/keys.md#test-live-modes) quando publicar seu aplicativo. ## Adicione um endpoint [Lado do servidor] Esta integração usa três objetos da API da Stripe: 1. Um [PaymentIntent](https://docs.stripe.com/api/payment_intents.md). A Stripe usa isso para representar sua intenção de coletar um pagamento de um cliente, acompanhando suas tentativas de cobrança e alterações de estado do pagamento durante todo o processo. 1. Um *cliente* (Customer objects represent customers of your business. They let you reuse payment methods and give you the ability to track multiple payments) (opcional). Para configurar uma forma de pagamento para pagamentos futuros, ela precisa estar vinculada a um cliente. Crie um objeto Customer quando o cliente abrir uma conta na sua empresa. Se o cliente pagar como convidado, você pode criar o objeto Customer antes do pagamento e associá-lo à sua representação interna da conta do cliente, mais tarde. 1. Uma chave efêmera de cliente (opcional). Os dados do objeto Customer são confidenciais e não podem ser recuperados diretamente do aplicativo. Uma chave efêmera concede ao SDK acesso temporário ao cliente. Se você quiser salvar cartões e permitir que clientes recorrentes reutilizem cartões salvos, você precisa dos objetos Customer e Customer Ephemeral Key para sua integração. Caso contrário, você poderá omitir esses objetos. Por motivos de segurança, seu aplicativo não pode criar esses objetos. Em vez disso, adicione um endpoint ao servidor que: 1. Recuperar ou criar um Customer. 1. Criar uma chave efêmera para o Customer. 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), o [cliente](https://docs.stripe.com/api/payment_intents/create.md#create_payment_intent-customer) e um [grupo de transferência](https://docs.stripe.com/api/payment_intents/create.md#create_payment_intent-transfer_group) para associar posteriormente à transferência de fundos. 1. Retorna o *segredo do cliente* (The client secret is a unique key returned from Stripe as part of a PaymentIntent. This key lets the client access important fields from the PaymentIntent (status, amount, currency) while hiding sensitive ones (metadata, customer)) do Payment Intent, o `secret` da chave efêmera, o [ID do cliente](https://docs.stripe.com/api/customers/object.md#customer_object-id) e sua [chave publicável](https://dashboard.stripe.com/apikeys) ao aplicativo. As formas de pagamento mostradas aos clientes durante o processo de checkout também estão incluídas no PaymentIntent. Você pode permitir que a Stripe obtenha as formas de pagamento das [configurações do Dashboard](https://dashboard.stripe.com/settings/payment_methods) ou pode 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 a moeda, as restrições e outros parâmetros dessas formas de pagamento para criar a lista das que são 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. Ocultamos as formas de pagamento de menor prioridade em um menu de navegação. #### Gerenciar formas de pagamento no Dashboard Você pode clonar e executar uma implementação de exemplo deste endpoint diretamente no [CodeSandbox](https://codesandbox.io/p/devbox/suspicious-lalande-l325w6) para testar o comportamento. #### 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" # Create an Ephemeral Key for the Customer curl https://api.stripe.com/v1/ephemeral_keys \ -u <>: \ -H "Stripe-Version: 2026-02-25.clover" \ -X "POST" \ -d "customer"="{{CUSTOMER_ID}}" \ # Create a PaymentIntent curl https://api.stripe.com/v1/payment_intents \ -u <>: \ -X "POST" \ -d "customer"="{{CUSTOMER_ID}}" \ -d "amount"=10000 \ -d "currency"="usd" \ # In the latest version of the API, specifying the `automatic_payment_methods` parameter # is optional because Stripe enables its functionality by default. -d "automatic_payment_methods[enabled]"=true \ -d transfer_group="ORDER100" \ ``` #### Listar manualmente as formas de pagamento Você pode clonar e executar uma implementação de exemplo deste endpoint diretamente no [CodeSandbox](https://codesandbox.io/p/devbox/suspicious-lalande-l325w6) para testar o comportamento. #### 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" # Create an Ephemeral Key for the Customer curl https://api.stripe.com/v1/ephemeral_keys \ -u <>: \ -H "Stripe-Version: 2026-02-25.clover" \ -X "POST" \ -d "customer"="{{CUSTOMER_ID}}" \ # Create a PaymentIntent curl https://api.stripe.com/v1/payment_intents \ -u <>: \ -X "POST" \ -d "customer"="{{CUSTOMER_ID}}" \ -d "amount"=10000 \ -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 transfer_group="ORDER100" \ ``` 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 saber 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. | ## Criar uma transferência [Lado do servidor] No seu servidor, envie fundos da sua conta para uma conta conectada criando uma [Transferência](https://docs.stripe.com/api/transfers/create.md) e especificando o `transfer_group` utilizado. ```curl curl https://api.stripe.com/v1/transfers \ -u "<>:" \ -d amount=7000 \ -d currency=usd \ -d destination="{{CONNECTEDACCOUNT_ID}}" \ -d transfer_group=ORDER100 ``` Os valores de transferência e cobrança não precisam ser iguais. Você pode dividir uma única cobrança entre várias transferências ou incluir várias cobranças em uma única transferência. O exemplo a seguir cria uma transferência adicional associada ao mesmo `transfer_group`. ```curl curl https://api.stripe.com/v1/transfers \ -u "<>:" \ -d amount=2000 \ -d currency=usd \ -d destination={{OTHER_CONNECTED_ACCOUNT_ID}} \ -d transfer_group=ORDER100 ``` ### Opções de transferência Você pode atribuir qualquer valor à string `transfer_group`, mas ela deve representar uma única ação de negócios. Também é possível fazer uma transferência sem associar uma cobrança ou `transfer_group`. Por exemplo, quando você paga um provedor, mas não há um pagamento a cliente associado. > O `transfer_group` identifica apenas objetos associados. Ele não afeta nenhuma funcionalidade padrão. Para evitar que uma transferência seja executada antes que os fundos da cobrança associada estejam disponíveis, use o atributo `source_transaction` da transferência. Por padrão, uma solicitação de transferência falha quando o valor excede o [saldo da conta disponível](https://docs.stripe.com/connect/account-balances.md) da plataforma. A Stripe não repete automaticamente solicitações de transferência malsucedidas. Você pode evitar falhas nas solicitações de transferência para transferências associadas a cobranças. Quando você especifica a cobrança associada [como a source_transaction da transferência](https://docs.stripe.com/connect/separate-charges-and-transfers.md#transfer-availability), a solicitação de transferência é bem-sucedida automaticamente. No entanto, não executamos a transferência até que os fundos dessa cobrança estejam disponíveis na conta da plataforma. > Se você usa cobranças e transferências separadas, leve isso em consideração quando planejar seu cronograma de repasses *payout* (A payout is the transfer of funds to an external account, usually a bank account, in the form of a deposit). Repasses automáticos podem interferir nas transferências que não têm uma `source_transaction` definida. ### Formas de pagamento assíncronas Se você estiver usando *formas de pagamento assíncronas* (Asynchronous payment methods can take up to several days to confirm whether the payment has been successful. During this time, the payment can't be guaranteed) (como débito ACH ou débito SEPA), aguarde um evento [charge.succeeded](https://docs.stripe.com/api/events/types.md#event_types-charge.succeeded) antes de criar uma transferência. Ao contrário das cobranças de destino, a Stripe não reverte automaticamente uma transferência se o pagamento assíncrono associado falhar. Se você criar uma transferência e o pagamento falhar posteriormente, o saldo da sua plataforma será debitado pelo valor da transferência. Você deverá então [reverter manualmente a transferência](https://docs.stripe.com/connect/separate-charges-and-transfers.md#reverse-transfers) para recuperar os fundos. ## Teste a integração #### Cartões | Número do cartão | Cenário | Como testar | | ------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------- | | 4242424242424242 | O pagamento com cartão é bem-sucedido e não precisa de autenticação. | Preencha o formulário do cartão de crédito usando o número do cartão de crédito com qualquer validade, CVC e código postal. | | 4000002500003155 | O pagamento com cartão precisa de *autenticação* (Strong Customer Authentication (SCA) is a regulatory requirement in effect as of September 14, 2019, that impacts many European online payments. It requires customers to use two-factor authentication like 3D Secure to verify their purchase). | Preencha o formulário do cartão de crédito usando o número do cartão de crédito com qualquer validade, CVC e código postal. | | 4000000000009995 | O cartão é recusado com um código de recusa como `insufficient_funds`. | Preencha o formulário do cartão de crédito usando o número do cartão de crédito com qualquer validade, CVC e código postal. | | 6205500000000000004 | O cartão UnionPay tem um comprimento variável de 13 a 19 dígitos. | Preencha o formulário do cartão de crédito usando o número do cartão de crédito com qualquer validade, CVC e código postal. | #### Débito bancário autenticado | Forma de pagamento | Cenário | Como testar | | ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Bancontact, iDEAL | Seu cliente não faz a autenticação na página de redirecionamento de uma forma de pagamento baseada em redirecionamento e notificação imediata. | Escolha qualquer forma de pagamento baseada em redirecionamento, preencha os dados obrigatórios e confirme o pagamento. Em seguida, clique em **Falhar pagamento de teste** na página de redirecionamento. | | Pay by Bank | O cliente paga com uma forma de pagamento baseada em redirecionamento e [notificação posterior](https://docs.stripe.com/payments/payment-methods.md#payment-notification). | Escolha a forma de pagamento, preencha os dados obrigatórios e confirme o pagamento. Em seguida, clique em **Concluir o pagamento de teste** na página de redirecionamento. | | Pay by Bank | Seu cliente não faz a autenticação na página de redirecionamento de uma forma de pagamento baseada em redirecionamento e notificação posterior. | Escolha a forma de pagamento, preencha os dados obrigatórios e confirme o pagamento. Em seguida, clique em **Falhar o pagamento de teste** na página de redirecionamento. | | BLIK | Os pagamentos BLIK falham de várias formas: falhas imediatas (por exemplo, o código está vencido ou inválido), erros atrasados (o banco recusa) ou limites de tempo (o cliente não respondeu a tempo). | Use padrões de e-mail para [simular as diferentes falhas.](https://docs.stripe.com/payments/blik/accept-a-payment.md#simulate-failures) | #### Débitos bancários | Forma de pagamento | Cenário | Como testar | | ---------------------- | ------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Débito automático SEPA | O cliente paga com débito automático SEPA. | Preencha o formulário usando o número de conta `AT321904300235473204`. Inicialmente, o status do PaymentIntent muda para processando e, três minutos depois, para bem-sucedido. | | Débito automático SEPA | O status da intenção de pagamento do cliente muda de `processing` para `requires_payment_method`. | Preencha o formulário usando o número de conta `AT861904300235473202`. | Consulte [Testes](https://docs.stripe.com/testing.md) para obter mais informações sobre como testar sua integração. ## Optional: Ativar Google Pay ### Configurar a integração Para usar o Google Pay, habilite a API Google Pay adicionando o seguinte à `` tag do seu **AndroidManifest.xml**: ```xml ... ``` Veja mais detalhes na [Configuração da API Google Pay](https://developers.google.com/pay/api/android/guides/setup) do Google Pay para Android. ### Adicionar Google Pay Para adicionar o Google Pay à sua integração, passe uma [PaymentSheet.GooglePayConfiguration](https://stripe.dev/stripe-android/paymentsheet/com.stripe.android.paymentsheet/-payment-sheet/-google-pay-configuration/index.html) com seu ambiente do Google Pay (produção ou teste) e o [código do país da sua empresa](https://dashboard.stripe.com/settings/account) quando inicializar [PaymentSheet.Configuration](https://stripe.dev/stripe-android/paymentsheet/com.stripe.android.paymentsheet/-payment-sheet/-configuration/index.html). #### Kotlin ```kotlin val googlePayConfiguration = PaymentSheet.GooglePayConfiguration( environment = PaymentSheet.GooglePayConfiguration.Environment.Test, countryCode = "US", currencyCode = "USD" // Required for Setup Intents, optional for Payment Intents ) val configuration = PaymentSheet.Configuration.Builder(merchantDisplayName = "My merchant name") .googlePay(googlePayConfiguration) .build() ``` ### Testar Google Pay O Google permite que você faça pagamentos de teste por meio de seu [Pacote de cartão de teste](https://developers.google.com/pay/api/android/guides/resources/test-card-suite). O Pacote de cartão de teste é compatível com os [cartões de teste](https://docs.stripe.com/testing.md) da Stripe. Você precisa testar o Google Pay usando um dispositivo Android físico em vez de um dispositivo simulado, em um país onde o Google Pay é compatível. Faça login em uma conta do Google em seu dispositivo de teste com um cartão real salvo na Carteira do Google. ## Optional: Personalizar a descrição Toda personalização é configurada usando o objeto [PaymentSheet.Configuration](https://stripe.dev/stripe-android/paymentsheet/com.stripe.android.paymentsheet/-payment-sheet/-configuration/index.html). ### Aparência Customize colors, fonts, and more to match the look and feel of your app by using the [appearance API](https://docs.stripe.com/elements/appearance-api/mobile.md?platform=android). ### Layout da forma de pagamento Configure o layout das formas de pagamento na planilha usando [paymentMethodLayout](https://stripe.dev/stripe-android/paymentsheet/com.stripe.android.paymentsheet/-payment-sheet/-configuration/-builder/index.html#2123253356%2FFunctions%2F2002900378). Você pode exibi-los horizontalmente, verticalmente ou deixar a Stripe otimizar o layout automaticamente. ![](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: Habilitar formas de pagamento adicionais Navegue para [Gerenciar formas de pagamento para suas contas conectadas](https://dashboard.stripe.com/settings/payment_methods/connected_accounts) no Dashboard para configurar quais formas de pagamento suas contas conectadas aceitam. As alterações nas configurações padrão se aplicam a todas as contas conectadas novas e existentes. Consulte os seguintes recursos para obter informações sobre formas de pagamento: - [Um guia de formas de pagamento](https://stripe.com/payments/payment-methods-guide#choosing-the-right-payment-methods-for-your-business) para ajudar você a escolher as formas de pagamento corretas para sua plataforma. - [Funções da conta](https://docs.stripe.com/connect/account-capabilities.md) para assegurar que as formas de pagamento escolhidas funcionem para suas contas conectadas. - Tabelas de [suporte a formas de pagamento e produtos](https://docs.stripe.com/payments/payment-methods/payment-method-support.md#product-support) para assegurar que suas formas de pagamento escolhidas funcionem para seus produtos da Stripe e fluxos de pagamento. Para cada forma de pagamento, você pode selecionar uma das seguintes opções no menu suspenso: | | | | | **Ativadas por padrão** | Suas contas conectadas aceitam esta forma de pagamento durante o checkout. Algumas formas de pagamento podem ser desativadas ou bloqueadas. Isso ocorre porque suas contas conectadas com *acesso ao Stripe Dashboard* (Platforms can provide connected accounts with access to the full Stripe Dashboard or the Express Dashboard. Otherwise, platforms build an interface for connected accounts using embedded components or the Stripe API) precisam ativá-las em sua página de configurações. | | **Desativadas por padrão** | Suas contas conectadas não aceitam esta forma de pagamento durante o checkout. Se você permitir que contas conectadas com *acessem o Stripe Dashboard* (Platforms can provide connected accounts with access to the full Stripe Dashboard or the Express Dashboard. Otherwise, platforms build an interface for connected accounts using embedded components or the Stripe API) para gerenciar suas próprias formas de pagamento, elas podem ativar esse recurso. | | **Bloqueadas** | Suas contas conectadas não aceitam esta forma de pagamento durante o checkout. Se você permitir que contas conectadas com *acessem o Stripe Dashboard* (Platforms can provide connected accounts with access to the full Stripe Dashboard or the Express Dashboard. Otherwise, platforms build an interface for connected accounts using embedded components or the Stripe API) para gerenciar suas próprias formas de pagamento, elas não têm a opção para ativar esse recurso. | ![Opções 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`. ## Especificar o comerciante da liquidação O comerciante da liquidação depende das [funções](https://docs.stripe.com/connect/account-capabilities.md) da conta e da forma de criação da cobrança. O comerciante da liquidação determina quais dados são usados para fazer a cobrança. Isso inclui a descrição no extrato (da plataforma ou da conta conectada) exibida sobre essa cobrança no extrato bancário ou de cartão de crédito do cliente. A especificação do comerciante da liquidação permite que você defina mais explicitamente para quem as cobranças são criadas. Por exemplo, algumas plataformas preferem ser o comerciante da liquidação porque o cliente final interage diretamente com a plataforma (como plataformas sob demanda). No entanto, algumas plataformas têm contas conectadas que interagem diretamente com os clientes finais (como lojas de uma plataforma de e-commerce). Nesses cenários, pode fazer mais sentido que a conta conectada seja o comerciante da liquidação. Você pode definir o parâmetro `on_behalf_of` para o ID de uma conta conectada para tornar essa conta o comerciante de liquidação do pagamento. Quando usar `on_behalf_of`: - As cobranças são *liquidadas* (When funds are available in your Stripe balance) no país da conta conectada e na *moeda de liquidação* (The settlement currency is the currency your bank account uses). - É usada a estrutura de tarifas do país da conta conectada. - A descrição no extrato da conta conectada é exibida no extrato do cartão de crédito do cliente. - Se a conta conectada estiver em um país diferente do da plataforma, o endereço e o número de telefone da conta conectada serão exibidos no extrato do cartão de crédito do cliente. - O número de dias que um [saldo pendente](https://docs.stripe.com/connect/account-balances.md) é retido antes de receber o repasse depende da configuração [delay_days](https://docs.stripe.com/api/accounts/create.md#create_account-settings-payouts-schedule-delay_days) na conta conectada. > #### API Accounts v2 > > Você não pode usar a API Accounts v2 para gerenciar as configurações de repasse. Use a API Accounts v1. Se `on_behalf_of` for omitido, a plataforma será a empresa registrada para o pagamento. > O parâmetro `on_behalf_of` só é aceito para contas conectadas com uma função de pagamentos, como [card_payments](https://docs.stripe.com/connect/account-capabilities.md#card-payments). As contas sujeitas ao [contrato de serviços de destinatário](https://docs.stripe.com/connect/service-agreement-types.md#recipient) não podem solicitar `card_payments` nem outras funções de pagamento. ```curl curl https://api.stripe.com/v1/payment_intents \ -u "<>:" \ -d amount=10000 \ -d currency=usd \ -d "automatic_payment_methods[enabled]"=true \ -d on_behalf_of="{{CONNECTEDACCOUNT_ID}}" \ -d transfer_group=ORDER100 ``` ![](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 servidor se comuniquem com a API da Stripe. Use as bibliotecas oficiais para acessar a API da Stripe partir do 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. ## Adicione um endpoint [Lado do servidor] Esta integração usa três objetos da API da Stripe: 1. Um [PaymentIntent](https://docs.stripe.com/api/payment_intents.md). A Stripe usa isso para representar sua intenção de coletar um pagamento de um cliente, acompanhando suas tentativas de cobrança e alterações de estado do pagamento durante todo o processo. 1. Um *cliente* (Customer objects represent customers of your business. They let you reuse payment methods and give you the ability to track multiple payments) (opcional). Para configurar uma forma de pagamento para pagamentos futuros, ela precisa estar vinculada a um cliente. Crie um objeto Customer quando o cliente abrir uma conta na sua empresa. Se o cliente pagar como convidado, você pode criar o objeto Customer antes do pagamento e associá-lo à sua representação interna da conta do cliente, mais tarde. 1. Uma chave efêmera de cliente (opcional). Os dados do objeto Customer são confidenciais e não podem ser recuperados diretamente do aplicativo. Uma chave efêmera concede ao SDK acesso temporário ao cliente. Se você quiser salvar cartões e permitir que clientes recorrentes reutilizem cartões salvos, você precisa dos objetos Customer e Customer Ephemeral Key para sua integração. Caso contrário, você poderá omitir esses objetos. Por motivos de segurança, seu aplicativo não pode criar esses objetos. Em vez disso, adicione um endpoint ao servidor que: 1. Recuperar ou criar um Customer. 1. Criar uma chave efêmera para o Customer. 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), o [cliente](https://docs.stripe.com/api/payment_intents/create.md#create_payment_intent-customer) e um [grupo de transferência](https://docs.stripe.com/api/payment_intents/create.md#create_payment_intent-transfer_group) para associar posteriormente à transferência de fundos. 1. Retorna o *segredo do cliente* (The client secret is a unique key returned from Stripe as part of a PaymentIntent. This key lets the client access important fields from the PaymentIntent (status, amount, currency) while hiding sensitive ones (metadata, customer)) do Payment Intent, o `secret` da chave efêmera, o [ID do cliente](https://docs.stripe.com/api/customers/object.md#customer_object-id) e sua [chave publicável](https://dashboard.stripe.com/apikeys) ao aplicativo. As formas de pagamento mostradas aos clientes durante o processo de checkout também estão incluídas no PaymentIntent. Você pode permitir que a Stripe obtenha as formas de pagamento das [configurações do Dashboard](https://dashboard.stripe.com/settings/payment_methods) ou pode 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 a moeda, as restrições e outros parâmetros dessas formas de pagamento para criar a lista das que são 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. Ocultamos as formas de pagamento de menor prioridade em um menu de navegação. #### Gerenciar formas de pagamento no Dashboard Você pode clonar e executar uma implementação de exemplo deste endpoint diretamente no [CodeSandbox](https://codesandbox.io/p/devbox/suspicious-lalande-l325w6) para testar o comportamento. #### 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" # Create an Ephemeral Key for the Customer curl https://api.stripe.com/v1/ephemeral_keys \ -u <>: \ -H "Stripe-Version: 2026-02-25.clover" \ -X "POST" \ -d "customer"="{{CUSTOMER_ID}}" \ # Create a PaymentIntent curl https://api.stripe.com/v1/payment_intents \ -u <>: \ -X "POST" \ -d "customer"="{{CUSTOMER_ID}}" \ -d "amount"=10000 \ -d "currency"="usd" \ # In the latest version of the API, specifying the `automatic_payment_methods` parameter # is optional because Stripe enables its functionality by default. -d "automatic_payment_methods[enabled]"=true \ -d transfer_group="ORDER100" \ ``` #### Listar manualmente as formas de pagamento Você pode clonar e executar uma implementação de exemplo deste endpoint diretamente no [CodeSandbox](https://codesandbox.io/p/devbox/suspicious-lalande-l325w6) para testar o comportamento. #### 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" # Create an Ephemeral Key for the Customer curl https://api.stripe.com/v1/ephemeral_keys \ -u <>: \ -H "Stripe-Version: 2026-02-25.clover" \ -X "POST" \ -d "customer"="{{CUSTOMER_ID}}" \ # Create a PaymentIntent curl https://api.stripe.com/v1/payment_intents \ -u <>: \ -X "POST" \ -d "customer"="{{CUSTOMER_ID}}" \ -d "amount"=10000 \ -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 transfer_group="ORDER100" \ ``` 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 saber mais detalhes sobre o que é aceito. ## Integrar a descrição da compra [Lado do cliente] Antes de exibir o Element Pagamento para dispositivos móveis, a página de checkout deve: - Mostrar os produtos sendo comprados e o valor total - Coletar todos os dados de entrega necessários - Incluir um botão de checkout para apresentar a IU da Stripe No checkout do aplicativo, faça uma solicitação de rede para o endpoint de backend criado por você na etapa anterior e chame o `initPaymentSheet` do hook `useStripe`. ```javascript export default function CheckoutScreen() { const { initPaymentSheet, presentPaymentSheet } = useStripe(); const [loading, setLoading] = useState(false); const fetchPaymentSheetParams = async () => { const response = await fetch(`${API_URL}/payment-sheet`, { method: 'POST', headers: { 'Content-Type': 'application/json', }, }); const { paymentIntent, ephemeralKey, customer } = await response.json(); return { paymentIntent, ephemeralKey, customer, }; }; const initializePaymentSheet = async () => { const { paymentIntent, ephemeralKey, customer, } = await fetchPaymentSheetParams(); const { error } = await initPaymentSheet({ merchantDisplayName: "Example, Inc.", customerId: customer, customerEphemeralKeySecret: ephemeralKey, paymentIntentClientSecret: paymentIntent, // Set `allowsDelayedPaymentMethods` to true if your business can handle payment //methods that complete payment after a delay, like SEPA Debit and Sofort. allowsDelayedPaymentMethods: true, defaultBillingDetails: { name: 'Jane Doe', } }); if (!error) { setLoading(true); } }; const openPaymentSheet = async () => { // see below }; useEffect(() => { initializePaymentSheet(); }, []); return (