Crie cobranças de destino

Crie cobranças na conta da sua plataforma, colete tarifas e transfira imediatamente os fundos restantes para suas contas conectadas.

Crie cobranças de destino quando os clientes fizerem transações com sua plataforma para produtos ou serviços fornecidos por suas contas conectadas e você transferir fundos imediatamente para suas contas conectadas. Com este tipo de cobrança:

Você cria uma cobrança na conta da sua plataforma.
Você determina se alguns ou todos os fundos são transferidos para a conta conectada.
O custo das tarifas da Stripe e de reembolsos ou estornos é debitado da sua conta.

Esse tipo de cobrança é mais ideal para marketplaces como o Airbnb, um marketplace de aluguel residencial, ou a Lyft, um aplicativo de transporte por aplicativo.

Com algumas exceções, se a sua plataforma e uma conta conectada não estiverem na mesma região, você deverá especificar a conta conectada como o comerciante de liquidação usando o parâmetro on_behalf_of no Payment Intent.

Recomendamos usar cobranças de destino para contas conectadas que não têm acesso ao Stripe Dashboard completo.

Web

iOS

Android

React Native

Essa integração combina todas as etapas exigidas para pagar – coleta dos dados de pagamento e confirmação do pagamento – em uma única folha que é exibida com base no seu aplicativo.

Configurar a Stripe
Lado do servidor
Lado do cliente

Primeiro, você precisa de uma conta Stripe. Cadastre-se agora.

Lado do servidor

Esta integração exige que os endpoints do seu servidor se comuniquem com a API da Stripe. Use as bibliotecas oficiais para acessar a API da Stripe pelo seu servidor:

Lado do cliente

O SDK do React Native é de código aberto e totalmente documentado. Internamente, utiliza as SDKs de iOS nativo e 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):

Command Line
yarn add @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.

Observação

Recomendamos seguir o guia oficial do TypeScript 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 em publishableKey é necessária. O exemplo a seguir mostra como inicializar a Stripe usando o componente StripeProvider.

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 (
    <StripeProvider
      publishableKey={publishableKey}
      merchantIdentifier="merchant.identifier" // required for Apple Pay
      urlScheme="your-url-scheme" // required for 3D Secure and bank redirects
    >
      {/* Your app code here */}
    </StripeProvider>
  );
}

Observação

Use suas chaves de API de teste enquanto testa e desenvolve, e as chaves de modo de produção quando publica seu aplicativo.

Adicionar um endpoint
Lado do servidor

Nota

Para exibir o PaymentSheet antes de criar um PaymentIntent, consulte Colete os dados de pagamento antes de criar um Intent.

Esta integração usa três objetos da API da Stripe:

PaymentIntent: A Stripe usa isso para representar sua intenção de coletar o pagamento de um cliente, acompanhando suas tentativas de cobrança e alterações no estado do pagamento durante todo o processo.
(Opcional) Customer: Para configurar uma forma de pagamento para pagamentos futuros, vincule-a a um Customer. 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.
(Opcional) CustomerSession: Os dados do objeto Customer são confidenciais e não podem ser recuperados diretamente do aplicativo. Uma CustomerSession concede ao SDK acesso temporário com escopo definido ao cliente e fornece opções de configuração adicionais. Consulte uma lista completa de opções de configuração.

Observação

Se você nunca salva cartões para um cliente e não permite que clientes retornando reutilizem cartões salvos, é possível omitir os objetos cliente e CustomerSession da sua integração.

Por motivos de segurança, o aplicativo não pode criar esses objetos. Para isso, adicione um endpoint ao servidor para:

Recuperar ou criar um Customer.
Cria uma CustomerSession para o cliente.
Cria um PaymentIntent com o valor, a moeda e o cliente.
Retorna o segredo do cliente do Payment Intent, o client_secret da CustomerSession, o id do Cliente e sua chave publicável para seu aplicativo.

As formas de pagamento mostradas aos clientes durante o processo de checkout também são incluídas no PaymentIntent. Você pode permitir que a Stripe obtenha as formas de pagamento das configurações do Dashboard ou listá-las manualmente. Independentemente da opção escolhida, saiba que a moeda passada no PaymentIntent filtra as formas de pagamento mostradas para o cliente. Por exemplo, se você passar EUR no eur e a OXXO estiver ativada no Dashboard, a OXXO não será exibida ao cliente porque a OXXO não aceita pagamentos em eur.

Se sua integração não exige uma opção baseada em código para oferecer formas de pagamento, a Stripe recomenda a opção automática. Isso ocorre porque a Stripe avalia a moeda, as restrições de forma de pagamento e outros parâmetros para determinar a lista de formas de pagamento aceitas. Priorizamos as formas de formas de pagamento que aumentam a conversão e que são mais relevantes para a moeda e a localização do cliente.

Você pode gerenciar formas de pagamento no Dashboard. A Stripe processa a devolução de formas de pagamento qualificadas com base em fatores como valor, moeda e fluxo de pagamento da transação. O PaymentIntent é criado usando as formas de pagamento configuradas no Dashboard. Se não quiser usar o Dashboard ou se quiser especificar formas de pagamento manualmente, você pode listá-las usando o atributo payment_method_types.

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.

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 (
    <Screen>
      <Button
        variant="primary"
        disabled={!loading}
        title="Checkout"
        onPress={openPaymentSheet}
      />
    </Screen>
  );
}

Quando o cliente tocar no botão Checkout, chame presentPaymentSheet() para abrir a descrição. Depois que o cliente finalizar o pagamento, a descrição será descartada e a promessa será resolvida com um StripeError<PaymentSheetError> opcional.

export default function CheckoutScreen() {
  // continued from above

  const openPaymentSheet = async () => {
    const { error } = await presentPaymentSheet();

    if (error) {
      Alert.alert(`Error code: ${error.code}`, error.message);
    } else {
      Alert.alert('Success', 'Your order is confirmed!');
    }
  };

  return (
    <Screen>
      <Button
        variant="primary"
        disabled={!loading}
        title="Checkout"
        onPress={openPaymentSheet}
      />
    </Screen>
  );
}

Se não houver erro, informe ao usuário que está tudo pronto (por exemplo, exibindo uma tela de confirmação de pedido).

Configurar allowsDelayedPaymentMethods como verdadeiro permite formas de pagamento de notificação assíncrona como contas bancárias dos EUA. Para essas formas de pagamento, o status final do pagamento não é conhecido quando o PaymentSheet é concluído, sendo efetivado ou não posteriormente. Se você aceitar esses tipos de formas de pagamento, informe o cliente que seu pedido está confirmado e somente processe o pedido (por exemplo, fazendo o envio do produto) quando o pagamento for bem-sucedido.

Configurar um URL de retorno (somente iOS)
Lado do cliente

O cliente pode sair do seu aplicativo para autenticar (por exemplo, no Safari ou no aplicativo bancário). Para permitir que eles voltem ao seu aplicativo após a autenticação, configure um esquema de URL personalizado e configure seu aplicativo delegado para encaminhar o URL ao SDK. A Stripe não aceita links universais.

Além disso, defina o returnURL no seu objeto PaymentSheet.Configuration para o URL do seu aplicativo.

var configuration = PaymentSheet.Configuration()
configuration.returnURL = "your-app://stripe-redirect"

Gerenciar eventos pós-pagamento

Stripe envia um evento payment_intent.succeeded quando o pagamento é concluído. Use a ferramenta Dashboard webhook ou siga o guia de webhooks 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 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	Enviado quando um cliente conclui um pagamento com êxito.	Envie ao cliente uma confirmação de pedido e processe o pedido.
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	Enviado quando um cliente tenta fazer um pagamento, mas o pagamento falha.	Se um pagamento passa de `processing` para `payment_failed`, ofereça ao cliente outra tentativa para pagar.

Testar a integração

Número do cartão	Cenário	Como testar
	O pagamento com cartão é bem-sucedido e não precisa de autenticação.	Preencha o formulário do cartão de crédito usando o número do cartão de crédito com qualquer validade, CVC e código postal.
	O pagamento com cartão precisa de autenticação.	Preencha o formulário do cartão de crédito usando o número do cartão de crédito com qualquer validade, CVC e código postal.
	O cartão é recusado com um código de recusa como `insufficient_funds`.	Preencha o formulário do cartão de crédito usando o número do cartão de crédito com qualquer validade, CVC e código postal.
	O cartão UnionPay tem um comprimento variável de 13 a 19 dígitos.	Preencha o formulário do cartão de crédito usando o número do cartão de crédito com qualquer validade, CVC e código postal.

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

OpcionalAtivar Apple Pay

Solicitar um ID de comerciante da Apple

Obtenha um ID de comerciante da Apple solicitando um novo identificador no site de desenvolvedores da Apple.

Preencha o formulário com descrição e identificador. A descrição é para seu controle e pode ser modificada no futuro. A Stripe recomenda que você use o nome do aplicativo como identificador (por exemplo, merchant.com.{{YOUR_APP_NAME}}).

Criar um certificado do Apple Pay

Crie um certificado para criptografia de dados de pagamento pelo aplicativo.

Vá até Configurações de certificado do iOS 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 no Dashboard para obter um novo CSR e certificado.

Integrar com Xcode

Adicione as funções do Apple Pay ao aplicativo. No Xcode, abra as configurações do projeto, clique na guia Signing & Capabilities e adicione o recurso Apple Pay. Talvez seja necessário fazer login na sua conta de desenvolvedor. Selecione o ID de comerciante criado anteriormente e o aplicativo já pode aceitar Apple Pay.

Habilitar o recurso Apple Pay no Xcode

Adicionar Apple Pay

Passe seu ID de comerciante quando criar StripeProvider:

import { StripeProvider } from '@stripe/stripe-react-native';

function App() {
  return (
    <StripeProvider
      publishableKey="pk_test_TYooMQauvdEDq54NiTphI7jx"

      merchantIdentifier="MERCHANT_ID"
    >
      // Your app code here
    </StripeProvider>
  );
}

Quando você chamar initPaymentSheet, passe seus ApplePayParams:

await initPaymentSheet({
  // ...
  applePay: {
    merchantCountryCode: 'US',
  },
});

Rastreamento de pedidos

Para adicionar informações de rastreamento de pedido no iOS 16 ou mais recente, configure uma função de retorno de chamada setOrderTracking. A Stripe chama sua implementação após a conclusão do pagamento, mas antes que o iOS ignore a descrição de compra do Apple Pay.

Na implementação da função de retorno de chamada setOrderTracking, obtenha os detalhes do pedido concluído no seu servidor e passe esses dados à função de completion informada.

Para saber mais sobre rastreamento de pedidos, consulte a documentação de pedidos da carteira da Apple.

await initPaymentSheet({
  // ...
  applePay: {
    // ...
    setOrderTracking: async complete => {
      const apiEndpoint =
        Platform.OS === 'ios'
          ? 'http://localhost:4242'
          : 'http://10.0.2.2:4567';
      const response = await fetch(
        `${apiEndpoint}/retrieve-order?orderId=${orderId}`,
        {
          method: 'GET',
          headers: {
            'Content-Type': 'application/json',
          },
        },
      );
      if (response.status === 200) {
        const orderDetails = await response.json();
        // orderDetails should include orderIdentifier, orderTypeIdentifier,
        // authenticationToken and webServiceUrl
        complete(orderDetails);
      }
    },
  },
});

OpcionalAtivar Google Pay

Configure a integração

Para usar o Google Pay, habilite a API Google Pay adicionando o seguinte à <application> tag do seu AndroidManifest.xml:

AndroidManifest.xml
<application>
  ...
  <meta-data
    android:name="com.google.android.gms.wallet.api.enabled"
    android:value="true" />
</application>

Veja mais detalhes na Configuração da API Google Pay do Google Pay para Android.

Adicionar Google Pay

Quando você inicializar PaymentSheet, defina merchantCountryCode como o código de país da sua empresa e defina googlePay como true.

Você também pode usar o ambiente de teste passando o parâmetro testEnv. Você só pode testar o Google Pay em um dispositivo Android físico. Siga a documentação do React Native para testar seu aplicativo em um dispositivo físico.

const { error, paymentOption } = await initPaymentSheet({
  // ...
  googlePay: {
    merchantCountryCode: 'US',
    testEnv: true, // use test environment
  },
});

OpcionalHabilitar leitura de cartões (somente iOS)
Lado do cliente

Para habilitar o suporte à leitura de cartão, defina a NSCameraUsageDescription (Privacidade - Descrição de uso de câmera) no Info.plist do seu aplicativo e informe um motivo para acessar a câmera (por exemplo, “Para ler cartões”). Dispositivos com iOS 13 ou versão mais recente aceitam a leitura de cartões.

OpcionalPersonalizar a descrição

Toda personalização é configurada usando initPaymentSheet.

Aparência

Personalize cores, fontes e outros atributos de acordo com a aparência do aplicativo usando a API Appearance.

Nome de exibição do comerciante

Especifique o nome da empresa exibido para o cliente definindo merchantDisplayName. Por padrão, este é o nome do seu aplicativo.

await initPaymentSheet({
  // ...
  merchantDisplayName: 'Example Inc.',
});

Modo escuro

Por padrão, o PaymentSheet se adapta automaticamente às configurações de aparência do sistema do usuário (modo claro e escuro). É possível alterar isso configurando a propriedade style como modo alwaysLight ou alwaysDark no iOS.

await initPaymentSheet({
  // ...
  style: 'alwaysDark',
});

No Android, configure o modo claro ou escuro no seu aplicativo:

// force dark
AppCompatDelegate.setDefaultNightMode(AppCompatDelegate.MODE_NIGHT_YES)
// force light
AppCompatDelegate.setDefaultNightMode(AppCompatDelegate.MODE_NIGHT_NO)

Dados de faturamento padrão

Para definir valores padrão para dados de cobrança coletados no PaymentSheet, configure a propriedade defaultBillingDetails. A PaymentSheet preenche previamente seus campos com os valores que você informou.

await initPaymentSheet({
  // ...
  defaultBillingDetails: {
      email: 'foo@bar.com',
      address: {
        country: 'US',
      },
  },
});

Coletar dados de cobrança

Use billingDetailsCollectionConfiguration para especificar como você deseja coletar dados de cobrança no PaymentSheet.

Você pode coletar o nome, e-mail, número de telefone e endereço do cliente.

Se não pretende coletar os valores exigidos pela forma de pagamento, faça o seguinte:

Anexe os valores não coletados por PaymentSheet à propriedade defaultBillingDetails.
Defina billingDetailsCollectionConfiguration.attachDefaultsToPaymentMethod como true.

await initPaymentSheet({
  // ...
  defaultBillingDetails: {
    email: 'foo@bar.com',
  }
  billingDetailsCollectionConfiguration: {
    name: PaymentSheet.CollectionMode.ALWAYS,
    email: PaymentSheet.CollectionMode.NEVER,
    address: PaymentSheet.AddressCollectionMode.FULL,
    attachDefaultsToPaymentMethod: true
  },
});

Observação

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.

OpcionalConclua o pagamento em sua IU

Você pode exibir a Payment Sheet apenas para coletar dados da forma de pagamento e depois chamar um método confirm para concluir o pagamento na IU do aplicativo. Isso é útil quando você tem um botão de compra personalizado ou precisa de mais etapas após a coleta dos dados do pagamento.

Observação

Um exemplo de integração está disponível no GitHub.

Primeiro, chame initPaymentSheet e passe customFlow: true. initPaymentSheet é resolvido com uma opção de pagamento inicial que contém uma imagem e um rótulo representando a forma de pagamento do cliente. Atualize a IU com esses dados.

const {
  initPaymentSheet,
  presentPaymentSheet,
  confirmPaymentSheetPayment,
} = useStripe()

const { error, paymentOption } = await initPaymentSheet({
  customerId: customer,
  customerEphemeralKeySecret: ephemeralKey,
  paymentIntentClientSecret: paymentIntent,
  customFlow: true,
  merchantDisplayName: 'Example Inc.',
});
// Update your UI with paymentOption

Use presentPaymentSheet para coletar detalhes de pagamento. Quando o cliente termina, a folha se desfaz por si mesma e resolve a promessa. Atualize sua IU com os detalhes da forma de pagamento selecionada.

const { error, paymentOption } = await presentPaymentSheet();

Use confirmPaymentSheetPayment para confirmar o pagamento. Isso é resolvido com o resultado do pagamento.

const { error } = await confirmPaymentSheetPayment();

if (error) {
  Alert.alert(`Error code: ${error.code}`, error.message);
} else {
  Alert.alert(
    'Success',
    'Your order is confirmed!'
  );
}

OpcionalHabilite mais formas de pagamento

Configure formas de pagamento para a sua conta na página Formas de pagamento no Stripe Dashboard. Pagamentos por cartão, Google Pay e Apple Pay estão habilitados por padrão, mas você pode ativar e desativar formas de pagamento conforme a necessidade. Suas contas conectadas não podem personalizar suas próprias formas de pagamento.

Antes de exibir o formulário de pagamento a um cliente, a Stripe avalia a moeda, as restrições de forma de pagamento e outros parâmetros para determinar a lista de formas de pagamento aceitas. O formulário de pagamento prioriza as formas de pagamento que aumentam a conversão e são mais relevantes para a moeda e o local do cliente. As formas de pagamento de prioridade menor ficam ocultas em um menu de navegação.

Tarifas cobradas

Quando um pagamento é processado, em vez de transferir o valor total da transação para uma conta conectada, sua plataforma pode decidir cobrar uma parte do valor da transação na forma de tarifas. Você pode definir os preços das tarifas de duas maneiras diferentes:

Use a ferramenta de preços da plataforma para definir e testar as regras de preços das tarifas da plataforma. No momento, esse recurso no-code no Stripe Dashboard só está disponível para plataformas responsáveis pelo pagamento das tarifas da Stripe.
Defina internamente as regras de preços, especificando as tarifas diretamente em um PaymentIntent usando o parâmetro application_fee_amount ou transfer_data[amount]. As tarifas definidas com esse método substituem a lógica de preços especificada na ferramenta de preços da plataforma.

Ao criar cobranças com application_fee_amount, o valor total da cobrança é imediatamente transferido da plataforma para a conta transfer_data[destination] depois que a cobrança é capturada. O valor application_fee_amount (limitado ao valor total da cobrança) é transferido de volta à plataforma em seguida.

After the application fee is collected, an Application Fee object is created. You can view a list of application fees in the Dashboard, with the application fees, or in Sigma. You can also use the amount property on the application fee object for itemized fee reporting.

Quando usar um application_fee_amount, lembre-se:

O application_fee_amount é limitado ao valor total da transação.
O application_fee_amount é sempre computado na mesma moeda da transação.
A tarifa da plataforma é liquidada na mesma moeda de liquidação da conta conectada. Para cobranças de destino internacionais, isso pode diferir da moeda de liquidação da sua plataforma.
Sua plataforma paga a tarifa da Stripe após a transferência do application_fee_amount para sua conta.
Nenhuma tarifa da Stripe adicional é aplicada ao valor.
Sua plataforma pode usar relatórios integrados de tarifas da plataforma para reconciliar as tarifas cobradas.
Em dashboards ou componentes hospedados na Stripe como o componente de detalhes do pagamento, sua conta conectada pode visualizar o valor total e o valor da tarifa da plataforma.

Fluxo de fundos com Destination Charges

Com o código acima, o valor total da cobrança (US$ 10,00) é adicionado ao saldo pendente da conta conectada. O valor application_fee_amount (US$ 1,23) é subtraído do valor da cobrança e transferido para sua plataforma. As tarifas da Stripe (US$ 0,59) são subtraídas do saldo da conta da plataforma. O valor da tarifa da plataforma, deduzido das tarifas da Stripe (US$ 1,23 - US$ 0,59 = US$ 0,64), permanece no saldo da conta da plataforma.

Fluxo de fundos para Destination Charges

O application_fee_amount é disponibilizado no cronograma de transferências normal da conta da plataforma, assim como os fundos das cobranças normais da Stripe.

Especificar o comerciante da liquidação

O comerciante da liquidação depende das funções 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 no país da conta conectada e na moeda de liquidação.
É 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 é retido antes de receber o repasse depende da configuração delay_days na conta conectada.

Se on_behalf_of for omitido, a plataforma será a empresa registrada para o pagamento.

Cuidado

O parâmetro on_behalf_of só é aceito para contas conectadas com uma função de pagamentos, como card_payments. As contas sujeitas ao contrato de serviços de destinatário não podem solicitar card_payments nem outras funções de pagamento.

Emitir reembolsos

Se você está usando a API Payment Intents, os reembolsos devem ser emitidos para a cobrança criada mais recentemente.

As cobranças criadas na conta da plataforma podem ser reembolsadas usando a chave secreta da conta da plataforma. No reembolso de uma cobrança que tem transfer_data[destination], por padrão, a conta de destino mantém os fundos que foram transferidos para ela e o saldo negativo do reembolso é coberto pela conta da plataforma. Para recuperar os fundos da conta conectada a fim de cobrir o reembolso, defina o parâmetro reverse_transfer como true na criação do reembolso:

Por padrão, o valor total da cobrança é reembolsado, mas você pode criar um reembolso parcial definindo amount como um inteiro positivo.

Se o valor total da cobrança é reembolsado, toda a transferência é anulada. Caso contrário, um valor proporcional da transferência é anulado.

Reembolsar tarifas da plataforma

Quando você reembolsa uma cobrança com uma tarifa da plataforma, por padrão, a conta da plataforma mantém os fundos da tarifa da plataforma. Para devolver esses fundos para a conta conectada, defina o parâmetro refund_application_fee como true na criação do reembolso:

Se você reembolsar a tarifa da plataforma em uma cobrança de destino, precisa anular a transferência. Se o valor total da cobrança é reembolsado, toda a tarifa da plataforma é anulada. Caso contrário, um valor proporcional da tarifa da plataforma é reembolsado.

Você também pode informar um valor false para refund_application_fee e reembolsar a tarifa da plataforma separadamente usando a API.

Reembolsos com falha

Quando um reembolso falha ou você o cancela, o valor do reembolso não finalizado retorna ao seu saldo da conta da plataforma na Stripe. Crie uma transferência se precisar movimentar os fundos para a conta conectada.

Gerenciar contestações

Para cobranças de destino, com ou sem on_behalf_of, a Stripe debita os valores da contestação e as tarifas da conta da sua plataforma.

Recomendamos configurar um webhook para escutar eventos criados por contestação. Se isso acontecer, tente recuperar fundos da conta conectada anulando a transferência pelo Dashboard ou criando uma anulação de transferência.

Se o saldo da conta conectada for negativo, a Stripe tenta debitar sua conta externa se debit_negative_balances estiver definido como true.

Se você desafiar a contestação e vencer, poderá transferir os fundos que devolveu anteriormente para a conta conectada. Se sua plataforma tiver saldo insuficiente, a transferência falhará. Evite erros de saldo insuficiente adicionando fundos ao seu saldo da Stripe.

Erro comum

A retransferência de uma anulação anterior está sujeita a restrições de transferências internacionais, o que significa que você pode não como pagar sua conta conectada. Aguarde para recuperar transferências de pagamento internacionais contestadas para cobranças de destino com on_behalf_of até depois que a contestação for perdida.

Transferências ignoradas devido ao status da conta

Para pagamentos que usam formas de pagamento assíncronas (como ACH ou débito SEPA), há um atraso entre o momento em que o pagamento é autorizado e o momento em que os fundos são disponibilizados. Nesse período, se a conta de destino perder a funcionalidade de transferência necessária ou for fechada, a Stripe não poderá concluir a transferência conforme solicitado originalmente.

Quando a Stripe tenta criar uma transferência, mas não consegue devido à perda de funcionalidade ou exclusão da conta, a criação da transferência é ignorada e os fundos permanecem no saldo da sua plataforma.

Para detectar transferências ignoradas, ouça o evento webhook charge.updated. Se o valor de transfer_data no objeto Cobrança for null, será uma indicação de uma transferência ignorada.

Quando você detectar uma transferência ignorada, poderá criar uma transferência depois que o problema for resolvido, se apropriado para a sua empresa.

Componentes integrados do Connect

As Destination Charges são suportadas por componentes integrados do Connect. Ao usar o componente de pagamentos integrado, você pode habilitar suas contas conectadas a visualizar informações de pagamento a partir do seu site. Para Destination Charges com on_behalf_of, você pode usar o recurso destination_on_behalf_of_charge_management para permitir que suas contas conectadas visualizem mais detalhes, gerenciem reembolsos, contestações e permitam a captura de pagamentos.

Os seguintes componentes exibem informações sobre Destination Charges:

Componente de pagamentos: Exibe todos os pagamentos e contestações de uma conta.
Detalhes dos pagamentos: Exibe todos os pagamentos e contestações de uma conta.
Componente de lista de contestações: Exibe todas as contestações de uma conta.
Disputas para um componente de pagamento: Exibe as contestações para um único pagamento especificado. Você pode usá-lo para incluir a função de gerenciamento de contestação em uma página com sua IU de pagamentos.

Crie cobranças de destino

Crie cobranças na conta da sua plataforma, colete tarifas e transfira imediatamente os fundos restantes para suas contas conectadas.

Configurar a StripeLado do servidorLado do cliente

Lado do servidor

Lado do cliente

Observação

Inicialização da Stripe

Observação

Adicionar um endpointLado do servidor

Nota

Observação

Integrar a descrição da compraLado do cliente

Configurar um URL de retorno (somente iOS)Lado do cliente

Gerenciar eventos pós-pagamento

Testar a integração

OpcionalAtivar Apple Pay

Solicitar um ID de comerciante da Apple

Criar um certificado do Apple Pay

Integrar com Xcode

Adicionar Apple Pay

Rastreamento de pedidos

OpcionalAtivar Google Pay

Configure a integração

Adicionar Google Pay

OpcionalHabilitar leitura de cartões (somente iOS)Lado do cliente

OpcionalPersonalizar a descrição

Aparência

Nome de exibição do comerciante

Modo escuro

Dados de faturamento padrão

Coletar dados de cobrança

Observação

OpcionalConclua o pagamento em sua IU

Observação

OpcionalHabilite mais formas de pagamento

Tarifas cobradas

Fluxo de fundos com Destination Charges

Especificar o comerciante da liquidação

Cuidado

Emitir reembolsos

Reembolsar tarifas da plataforma

Reembolsos com falha

Gerenciar contestações

Erro comum

Transferências ignoradas devido ao status da conta

Componentes integrados do Connect

Veja também

Configurar a Stripe
Lado do servidor
Lado do cliente

Adicionar um endpoint
Lado do servidor

Integrar a descrição da compra
Lado do cliente

Configurar um URL de retorno (somente iOS)
Lado do cliente

OpcionalHabilitar leitura de cartões (somente iOS)
Lado do cliente