Pular para o conteúdo
Criar conta
 ou
Entrar
O logotipo da documentação da Stripe
/
Criar conta
Login

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.

Visualização privada

A capacidade de usar cobranças de destino em diferentes regiões sem o parâmetro on_behalf_of está em prévia privada para os seguintes cenários:

  • Sua plataforma está no Reino Unido ou na UE, e sua conta conectada está nos EUA.
  • Sua plataforma está nos EUA e sua conta conectada está no Reino Unido ou na UE.

Para solicitar acesso, fale conosco.

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

Integre a IU de pagamento incorporada da Stripe no checkout do seu aplicativo Android com a classe PaymentSheet.

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:

Command Line
# Available as a gem
sudo gem install stripe
Gemfile
# If you use bundler, you can add this line to your Gemfile
gem 'stripe'

Lado do cliente

O SDK da Stripe para Android é de código aberto e totalmente documentado.

Para instalar o SDK, adicione stripe-android ao bloco dependencies do arquivo app/build.gradle:

build.gradle.kts
plugins {
    id("com.android.application")
}

android { ... }

dependencies {
  // ...

  // Stripe Android SDK
  implementation("com.stripe:stripe-android:21.20.2")
  // Include the financial connections SDK to support US bank account as a payment method
  implementation("com.stripe:financial-connections:21.20.2")
}

Observação

Veja mais informações sobre o último lançamento de SDK e as versões anteriores na página Lançamentos no GitHub. Para receber notificações quando um novo lançamento for publicado, assista aos lançamentos do repositório.

Configure o SDK com sua chave publicável da Stripe, de modo que seja possível fazer solicitações à API Stripe, como em sua subcategoria Application:

import com.stripe.android.PaymentConfiguration

class MyApp : Application() {
    override fun onCreate() {
        super.onCreate()
        PaymentConfiguration.init(
            applicationContext,
            
"pk_test_TYooMQauvdEDq54NiTphI7jx"

        )
    }
}

Observação

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

Adicionar um endpoint
Lado do servidor

Nota

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

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

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

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

  3. (Opcional) Chave Efêmera de Cliente: as informações sobre o objeto Customer são confidenciais e não podem ser obtidas diretamente por um apliativo. Uma Chave Efêmera concede acesso temporário ao Cliente para o SDK.

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 Ephemeral Key da sua integração.

Por motivos de segurança, seu aplicativo não pode criar esses objetos. Em vez disso, adicione um endpoint ao seu servidor que:

  1. Recuperar ou criar um Customer.
  2. Criar uma chave efêmera para o Customer.
  3. Cria um PaymentIntent com o valor, a moeda e o cliente. Também é possível incluir opcionalmente o parâmetro automatic_payment_methods. A Stripe habilita sua funcionalidade por padrão na versão mais recente da API.
  4. Retorna o segredo do cliente do Payment Intent, o secret da chave efêmera, o id do cliente e sua chave publicável ao 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.

Observação

Teste uma implementação em execução desse endpoint no Glitch.

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.

Command Line
# Create a Customer (use an existing Customer ID if this is a returning customer)
curl https://api.stripe.com/v1/customers \
  -u 
sk_test_BQokikJOvBiI2HlWgH4olfQ2
: \
  -X "POST"

# Create an Ephemeral Key for the Customer
curl https://api.stripe.com/v1/ephemeral_keys \
  -u 
sk_test_BQokikJOvBiI2HlWgH4olfQ2
: \
  -H "Stripe-Version: 2025-06-30.basil" \
  -X "POST" \
  -d "customer"="{{CUSTOMER_ID}}" \

# Create a PaymentIntent
curl https://api.stripe.com/v1/payment_intents \
  -u 
sk_test_BQokikJOvBiI2HlWgH4olfQ2
: \
  -X "POST" \
  -d "customer"="{{CUSTOMER_ID}}" \
  -d "amount"=1099 \
  -d "currency"="eur" \
  # In the latest version of the API, specifying the `automatic_payment_methods` parameter
  # is optional because Stripe enables its functionality by default.
  -d "automatic_payment_methods[enabled]"=true \
  -d application_fee_amount="123" \
  -d "transfer_data[destination]"=
{{CONNECTED_ACCOUNT_ID}}
 \

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
  • Incluir um botão de checkout para apresentar a IU da Stripe

Inicializar uma instância de PaymentSheet dentro de onCreate da sua atividade de checkout, passando um método para gerenciar o resultado.

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, obtenha o segredo do cliente do PaymentIntent, o segredo da chave efêmera, o 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 as outras para usar quando você apresentar o PaymentSheet.

import androidx.compose.runtime.Composable
import androidx.compose.runtime.remember
import 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<PaymentSheet.CustomerConfiguration?>(null) }
  var paymentIntentClientSecret by remember { mutableStateOf<String?>(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(
          id = networkResult.customer,
          ephemeralKeySecret = networkResult.ephemeralKey
        )
        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 para apresentar a descrição da compra. Depois que o cliente conclui o pagamento, a descrição é descartada e o PaymentSheetResultCallback é chamado com um PaymentSheetResult.

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

@OptIn(ExperimentalCustomerSessionApi::class)
@Composable
fun App() {
  val paymentSheet = remember { PaymentSheet.Builder(::onPaymentSheetResult) }.build()
  val context = LocalContext.current
  var customerConfig by remember { mutableStateOf<PaymentSheet.CustomerConfiguration?>(null) }
  var paymentIntentClientSecret by remember { mutableStateOf<String?>(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(
          id = networkResult.customer,
          ephemeralKeySecret = networkResult.ephemeralKey
        )
        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")
    }
  }
}

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.

Gerenciar eventos pós-pagamento
Lado do servidor

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:

EventoDescriçãoAção
payment_intent.succeededEnviado quando um cliente conclui um pagamento com êxito.Envie ao cliente uma confirmação de pedido e processe o pedido.
payment_intent.processingEnviado 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_failedEnviado 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ãoCenárioComo 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.

Coletar tarifas

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.

Command Line
curl https://api.stripe.com/v1/payment_intents \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -d amount=1000 \
  -d currency=usd \
  -d "automatic_payment_methods[enabled]"=true \
  -d application_fee_amount=123 \
  -d "transfer_data[destination]"=
{{CONNECTED_ACCOUNT_ID}}

Após a coleta da tarifa da plataforma, um objeto Application Fee é criado. Veja uma lista de tarifas da plataforma no Dashboard, com as tarifas da plataforma ou em Sigma. Você também pode usar a propriedade amount no objeto Application Fee para obter relatórios detalhados de tarifas.

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

Command Line
curl https://api.stripe.com/v1/refunds \
  -u 
sk_test_BQokikJOvBiI2HlWgH4olfQ2
: \
  -d charge="{CHARGE_ID}" \
  -d reverse_transfer=true \

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:

Command Line
curl https://api.stripe.com/v1/refunds \
  -u 
sk_test_BQokikJOvBiI2HlWgH4olfQ2
: \
  -d charge="{CHARGE_ID}" \
  -d reverse_transfer=true \
  -d refund_application_fee=true \

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.

Veja também

Esta página foi útil?
SimNão